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 page numbers, enforce a maximum page size such as 100, and apply it to every collection endpoint.

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

Use the DataLoader pattern 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 combine it with query depth limiting and complexity analysis to block expensive queries.

Return 200 for successful GET/PATCH/PUT, 201 for POST creation, 204 for DELETE, 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/query parameter versioning for cleaner URLs. For GraphQL, evolve the schema by adding nullable fields and marking old ones with the @deprecated directive instead of removing them.

Skip it when you only need framework-specific implementation help, are doing infrastructure-only work without API contracts, or cannot change or version public interfaces. The guidance assumes you control the API contract and can apply design standards.