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 enforce a maximum page size such as 100 items.

REST fits resource-oriented services with simple caching and clear HTTP semantics, while GraphQL suits clients needing flexible queries and exact field selection. The skill covers both paradigms including migration scenarios between them.

Use the DataLoader pattern to batch and cache database requests per request cycle. The skill provides Python DataLoader implementations that batch load related entities like user orders in a single query.

Return 200 for successful reads, 201 for creation, 204 for deletion, 400 for malformed requests, 401 for missing auth, 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-based versioning for cleaner URLs. In GraphQL, prefer the @deprecated directive to evolve schemas gradually instead of removing fields.

Skip 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.