api-design-principles

Use offset-based pagination with page and page_size parameters for simple cases, or cursor-based pagination for large datasets. Always include pagination metadata like total count and pages, enforce a maximum page size, and apply it to every collection endpoint.

Use DataLoader to batch and cache database requests per request cycle. A DataLoader collects all IDs requested during a tick and fetches them in a single query, then maps results back in input order, eliminating per-item database round trips.

REST fits resource-oriented services with simple caching and clear HTTP semantics, while GraphQL suits clients needing flexible field selection and aggregated data from multiple sources. GraphQL requires DataLoaders, query depth limits, and complexity analysis to stay performant.

Return 200 for successful reads and updates, 201 for creation, 204 for deletion, 400 for malformed requests, 401 for missing authentication, 403 for insufficient permissions, 404 for missing resources, 422 for validation errors, and 429 for rate limiting.

Use URL versioning like /api/v1/users for clarity, or header versioning for cleaner URLs. In GraphQL, avoid versions entirely by adding nullable fields and marking old ones with the @deprecated directive instead of removing them.

The server enforces query depth limiting and complexity analysis to block expensive nested queries. Reduce nesting, request fewer list items per field, or split the operation into multiple smaller queries to stay within configured limits.