api-design-principles

Use plural nouns for collections like /api/users and map HTTP methods to actions: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. 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, compute an offset from the page number, and return a response containing items, total count, current page, and total pages. Cap page_size at a maximum like 100 to protect performance.

REST fits resource-centric services with simple caching and standard HTTP semantics, while GraphQL suits clients needing flexible queries that fetch exactly the fields they require. GraphQL adds schema and resolver complexity and requires DataLoaders to avoid N+1 query problems.

Use DataLoader to batch and cache per-request data fetching. A loader collects IDs from multiple resolver calls within one request and issues a single batched database query, then maps results back to the original request order.

Return 400 for malformed requests, 401 for missing authentication, 403 for forbidden access, 404 for missing resources, 409 for conflicts, and 422 for validation failures. Pair each with a consistent error body containing an error code, message, and details object.

Version your API from the start to allow breaking changes without disrupting existing clients. URL versioning like /api/v1/users is the most visible and common approach, while header and query-parameter versioning keep URLs stable at the cost of discoverability.