api-design

Use resource-based URLs with nouns instead of verbs, such as GET /users and POST /users/:id/posts. Apply correct HTTP methods and status codes, return consistent response structures, and support pagination, filtering, and sorting through query parameters.

REST suits resource-oriented services with simple caching and clear versioning via URLs. GraphQL fits clients needing flexible field selection and nested data, but requires DataLoader to prevent N+1 queries and depth limiting for security.

Use URL versioning like /api/v1 and /api/v2, or header versioning with Accept-Version. Send deprecation headers such as X-API-Deprecation to warn consumers, and maintain migration guides for breaking changes.

Use DataLoader to batch and cache database lookups within a single request. It collects IDs across resolvers, fetches them in one query, and returns results in the same order as the input IDs.

Return 200 for success, 201 for creation, 204 for empty success responses, 400 for invalid input, 401 for missing authentication, 403 for insufficient permissions, 404 for missing resources, 409 for conflicts, 422 for validation failures, and 429 for rate limiting.

Require an Idempotency-Key header and cache the processed result keyed by that value. On retry, return the cached response instead of processing the request again, preventing duplicate payments or resource creation.