api-design-principles

Use query parameters for pagination (page/page_size or cursor-based), filtering (status, search), and sorting (sort=-created_at). Return pagination metadata like total, pages, and has_next in the response body, and enforce a maximum page size such as 100.

REST fits resource-oriented CRUD with simple caching and clear HTTP semantics; GraphQL fits clients needing flexible field selection and aggregated queries. The skill covers both, including schema-first GraphQL design and REST resource modeling.

Use the DataLoader pattern to batch relationship loads into single queries per request. Combine it with query depth limiting and complexity analysis to protect against expensive nested queries.

Return 200 for successful GET/PATCH/PUT, 201 for POST creation, 204 for DELETE, 400 for malformed requests, 401/403 for auth failures, 404 for missing resources, 422 for validation errors, and 429 for rate limiting.

Avoid them when you only need framework-specific implementation help, when doing infrastructure-only work without API contracts, or when you cannot change or version public interfaces. The guidance targets design decisions, not library internals.