api-design-principles

Use plural nouns for resources (e.g., /api/users) and HTTP methods for actions: GET to retrieve, POST to create, PUT to replace, PATCH to update, and DELETE to remove. Avoid action-oriented URLs like /api/createUser, and nest related resources such as /api/users/{id}/orders.

Accept page and page_size query parameters with validation bounds, then return a response containing items, total count, current page, and total pages. The FastAPI example uses Query parameters with ge/le constraints and computes offset as (page - 1) * page_size.

REST suits resource-oriented services with standard CRUD operations and HTTP caching, while GraphQL lets clients request exactly the fields they need through a single typed endpoint. GraphQL requires DataLoaders to avoid N+1 query problems, whereas REST can suffer from over-fetching and under-fetching.

Use the DataLoader pattern to batch and cache database fetches per request. Implement a batch_load_fn that accepts a list of IDs, fetches all matching records in one query, and returns results mapped to the original ID order.

Return 200 for success, 201 for creation, 204 for no content, 400 for bad requests, 401 for unauthorized, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for validation errors, and 500 for server errors. Pair errors with a structured body containing error type, message, and details.

Version your API from day one to plan for breaking changes. Options include URL versioning (/api/v1/users), header versioning via the Accept header, or query parameter versioning; GraphQL APIs typically evolve through schema deprecation instead of explicit versions.