api-design-principles

Use query parameters like page and page_size with sensible defaults (e.g., 20 items, max 100), and return metadata including total count and page numbers. For large datasets, cursor-based pagination performs better than offset-based approaches.

Use the DataLoader pattern to batch and cache database requests within a single query execution. A DataLoader collects all IDs requested during resolution and fetches them in one query, eliminating per-item database round trips.

REST fits resource-oriented services with simple CRUD operations and caching needs, while GraphQL suits clients needing flexible data fetching from multiple related entities. GraphQL requires DataLoaders and query complexity limits to stay performant.

Return 200 for successful reads, 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, prefer the @deprecated directive to phase out fields gradually instead of publishing new schema versions.

Deeply nested queries trigger N+1 database fetches and unbounded complexity. Add DataLoaders for relationships, enforce query depth limits, and apply complexity analysis to reject expensive queries before execution.