api-design

# API Design Patterns Conventions and best practices for designing consistent, developer-friendly REST APIs. ## When to Activate - Designing new API endpoints - Reviewing existing API contracts - Adding pagination, filtering, or sorting - Implementing error handling for APIs - Planning API versioning strategy - Building public or partner-facing APIs ## Resource Design ### URL Structure ``` # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id # Sub-resources for relationships GET /api/v1/users/:id/orders POST /api/v1/users/:id/orders # Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login POST /api/v1/auth/refresh ``` ### Naming Rules ``` # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership # BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs /api/v1/users/123/getOrders # verb in nested resource ``` ## HTTP Methods and Status Codes ### Method Semantics | Method | Idempotent | Safe | Use For | |--------|-----------|------|---------| | GET | Yes | Yes | Retrieve resources | | POST | No | No | Create resources, trigger actions | | PUT | Yes | No | Full replacement of a resource | | PATCH | No* | No | Partial update of a resource | | DELETE | Yes | No | Remove a resource | *PATCH can be made idempotent with proper implementation ### Status Code Reference ``` # Success 200 OK — GET, PUT, PATCH (with response body) 201 Created — POST (include Location header) 204 No Content — DELETE, PUT (no response body) # Client Errors 400 Bad Request — Validation failure, malformed JSON 401 Unauthorized — Missing or invalid authentication 403 Forbidden — Authenticated but not authorized 404 Not Found — Resource doesn't exist 409 Conflict — Duplicate entry, state conflict 422 Unprocessable Entity — Semantically invalid (valid JSON, bad data) 429 Too Many Requests — Rate limit exceeded # Server Errors 500 Internal Server Error — Unexpected failure (never expose details) 502 Bad Gateway — Upstream service failed 503 Service Unavailable — Temporary overload, include Retry-After ``` ### Common Mistakes ``` # BAD: 200 for everything { "status": 200, "success": false, "error": "Not found" } # GOOD: Use HTTP status codes semantically HTTP/1.1 404 Not Found { "error": { "code": "not_found", "message": "User not found" } } # BAD: 500 for validation errors # GOOD: 400 or 422 with field-level details # BAD: 200 for created resources # GOOD: 201 with Location header HTTP/1.1 201 Created Locatio