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 DataLoaders to batch and cache database requests per request cycle. A DataLoader collects all IDs requested during resolver execution and fetches them in a single query, then maps results back in input order.

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

URL versioning like /api/v1/users is the most visible and easiest to route, while header versioning keeps URLs clean. In GraphQL, prefer schema evolution with the @deprecated directive instead of hard version cuts.

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.

Cursor pagination adds complexity and does not support jumping to arbitrary pages, so it is a poor fit for small datasets or admin interfaces needing numbered page navigation. Offset pagination is simpler and sufficient for those cases.