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, and apply it to every collection endpoint.

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, eliminating per-field database round trips for relationships.

REST fits resource-oriented services with simple caching and clear HTTP semantics, while GraphQL suits clients needing flexible field selection and aggregated data from multiple sources. The skill covers both, including migration considerations between the paradigms.

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.

Avoid it when you only need framework-specific implementation help, when doing infrastructure work without API contracts, or when you cannot change or version public interfaces. It focuses on design decisions, not library-specific coding.