AP
API Architecture
REST/GraphQL API design, versioning, and error handling patterns
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Use consistent URL patterns: plural nouns for resources, nested routes for relationships. Avoid verbs in URLs.
- Return proper HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.
- Version your API from day one. Use URL prefix (/v1/) or Accept header versioning.
- Validate all request bodies and query parameters at the boundary. Return structured error responses with error codes.
- Implement pagination for all list endpoints: cursor-based (preferred) or offset-based. Include total count and next/prev links.
- Use consistent error response format: { "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }.
- Add rate limiting with clear headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
- Support filtering, sorting, and field selection on list endpoints. Use query params: ?sort=-created_at&fields=id,name.
- Log all requests with correlation IDs. Pass the ID through to downstream services for distributed tracing.
- Use ETags or Last-Modified for caching. Return 304 Not Modified when the resource has not changed.