Building an API? Here's the checklist that saves you from 'why did we design it this way?' six months later.
URL Design
Use nouns, not verbs: /users/123 not /getUser?id=123. Plural nouns: /users not /user. Nest logically: /users/123/orders. Keep it flat — max 3 levels of nesting.
HTTP Methods
GET = read. POST = create. PUT = replace entirely. PATCH = update partially. DELETE = remove. Don't use GET for mutations.
Error Responses
Always return: HTTP status code + error message + error code (machine-readable). Include a request ID for debugging. Never expose stack traces in production.
Security
HTTPS only. Rate limiting (we use 20/min, 100/hour). Input validation on every endpoint. CORS restricted to allowed origins. API keys via headers, never in URLs.
Versioning
URL versioning (/v1/users) is simplest. Start with v1 from day one. Never break existing versions — add new endpoints instead.
Need to quickly prototype API endpoints? Try our AI code assistant — describe your endpoint and get working Express/Flask/FastAPI code instantly.