API Design

Use REST with consistent conventions. Follow the platform API guidelines (Microsoft, Google, Zalando) for details — the essentials below are consensus across all three.

URL conventions:

• URLs MUST be lowercase with hyphens: /order-items not /orderItems
• Collections MUST use plural nouns: /users, /orders
• Nesting SHOULD be shallow (max 2 levels): /users/{id}/orders
• URLs MUST NOT contain verbs — the HTTP method is the verb
• Trailing slashes MUST NOT be used
• Query params for filtering/sorting: /users?status=active&sort=-created_at

HTTP methods:

Status codes — use the right one:

• 200 OK — 201 Created — 204 No Content — 202 Accepted (async)
• 400 Bad Request — 401 Unauthorized — 403 Forbidden — 404 Not Found
• 409 Conflict — 422 Unprocessable Entity — 429 Too Many Requests
• 500 Internal Server Error — 503 Service Unavailable

Versioning: URL path versioning (/v1/users). Simple, explicit, industry consensus. Bump major version only for breaking changes.

Change History