api-design-principles

Use offset-based pagination with page and page_size query 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, and apply pagination to every collection endpoint.

REST fits resource-oriented services with predictable access patterns and simple caching needs. GraphQL suits clients needing flexible data fetching, such as mobile apps avoiding over-fetching, but requires DataLoaders and query complexity limits to stay performant.

Use the DataLoader pattern to batch and cache relationship lookups within a single request. A DataLoader collects all IDs requested during field resolution and fetches them in one database query, returning results mapped to the original order.

Return 200 for successful reads and updates, 201 for resource creation, 204 for deletions, 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 versioning entirely by deprecating fields with the @deprecated directive and adding new fields, since schemas evolve additively.

Avoid nesting deeper than two levels, such as /users/{id}/orders/{orderId}/items. Deeply nested URLs become brittle and hard to maintain; instead, expose nested resources as top-level endpoints filtered by query parameters.