api-design-principles

Use resource-oriented URLs with plural nouns like /api/users, and apply HTTP methods for actions: GET to retrieve, POST to create, PUT to replace, PATCH to update, and DELETE to remove. Avoid action-oriented endpoints like /api/createUser.

REST suits resource-oriented services with standard HTTP semantics and 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.

Use the DataLoader pattern to batch and cache data fetching. A DataLoader collects IDs requested within a resolver pass and fetches them in a single batch query, returning results mapped to the original IDs.

Common options are URL versioning (/api/v1/users), header versioning via the Accept header, and query parameter versioning. URL versioning is the most visible and widely adopted; choose one strategy and plan for breaking changes from day one.

Return correct HTTP status codes: 2xx for success, 4xx for client errors like 404 Not Found and 422 Unprocessable Entity, and 5xx for server errors. Standardize error response bodies with a consistent structure including error type, message, and details.

Cursor-based pagination following the Relay connection spec is recommended for large or frequently changing datasets. For small static lists, simple offset arguments may suffice, but connections with PageInfo provide consistent forward and backward navigation.