api-design-principles

Use query parameters like page and page_size with sensible defaults (e.g., 20 items per page, max 100). Return a paginated response containing items, total count, current page, and total pages. For large datasets, consider cursor-based pagination instead of offset-based.

Use the DataLoader pattern to batch and cache database requests. Create loader classes that collect multiple IDs and fetch them in a single query, then register loaders in the GraphQL context so resolvers share them across a request.

REST works well for simple CRUD resources, caching, and file uploads, while GraphQL suits clients needing flexible data fetching and complex relationships. GraphQL eliminates over-fetching but requires DataLoaders and query complexity limits to stay performant.

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 versioning via the Accept header for cleaner URLs. For GraphQL, prefer schema evolution with the @deprecated directive instead of versioning, since adding fields is backward compatible.

Avoid verbs in URLs like /api/createUser, deep nesting beyond two levels, inconsistent error formats, missing pagination on collections, and ignoring HTTP method semantics such as using POST for idempotent operations. Always document endpoints with OpenAPI.