Design Scalable REST and GraphQL APIs

Covers REST and GraphQL API design across principles, patterns, and versioning. REST patterns: resource-oriented collection design (nested resources named as nouns rather than action-oriented endpoints), pagination and filtering shown as a FastAPI endpoint, consistent error handling (a Pydantic ErrorResponse model, a STATUS_CODES mapping from success through unprocessable and internal_error, and raise_not_found and raise_validation_error helpers that return structured error, message, and details payloads), and HATEOAS for discoverable hypermedia links. GraphQL patterns: schema design in a schema.graphql file with clear type definitions, Relay-style cursor pagination, enums for type safety, custom scalars, separate query and mutation roots, and input and payload types for mutations; resolver design; and DataLoader-based batching to prevent the N+1 query problem - a UserLoader and an OrdersByUserLoader built on aiodataloader's batch_load_fn, each mapping results back to input order and grouping child records by parent ID, wired into a per-request context object. Covers three API versioning strategies - URL versioning (/api/v1/users), header versioning (an Accept header with a version parameter), and query-parameter versioning - and contrasts REST's resource-per-endpoint model against GraphQL's single-endpoint, multiple-operations model with client-specified field selection, strong typing, and built-in introspection.

Use it when designing REST or GraphQL API endpoints, structuring pagination and filtering, standardizing error responses, choosing a versioning strategy, or preventing the GraphQL N+1 query problem. Skip it for anything unrelated to API design or outside this scope.

Input is an API design decision - a resource endpoint shape, an error-handling contract, a GraphQL schema type, a resolver, or a versioning approach; output is the matching REST or GraphQL pattern with working Python code (FastAPI for REST, aiodataloader for GraphQL batching) ready to adapt, including the specific status-code mapping and structured error payload shape to standardize error handling across all of a service's endpoints rather than inventing a new format per route.

FastAPI and Pydantic for REST endpoint and error-model examples; the GraphQL schema definition language plus aiodataloader for resolver batching. Versioning strategies are framework-agnostic, covering URL path, HTTP header, or query parameter approaches.

Backend engineers designing or reviewing a REST or GraphQL API who need concrete resource, error-handling, pagination, and versioning patterns rather than an abstract API-style comparison. Particularly useful when a GraphQL API is showing N+1 query symptoms in production, since the DataLoader pattern is the concrete fix rather than a description of the problem.