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 pages, enforce a maximum page size, and apply it to every collection endpoint.

REST fits resource-oriented services with simple caching and clear HTTP semantics, while GraphQL suits clients needing flexible queries and exact field selection. GraphQL requires DataLoaders to avoid N+1 queries and complexity limits to prevent expensive queries.

Use the DataLoader pattern to batch and cache relationship lookups in a single query per request. Combine this with query depth limiting and complexity analysis to protect the API from expensive nested queries.

Return 200 for successful GET/PATCH/PUT, 201 for POST creation, 204 for DELETE, 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/query parameter versioning for cleaner URLs. For GraphQL, evolve the schema by adding nullable fields and marking old ones with the @deprecated directive instead of removing them.

Avoid verbs in URLs, inconsistent error formats, missing rate limits, deep resource nesting beyond two levels, and mirroring database schemas directly in the API. Standardize error responses and document endpoints with OpenAPI.