api-design-principles

Use plural nouns for resources like /api/users and map CRUD operations to HTTP methods: GET for retrieval, POST for creation, PUT for full replacement, PATCH for partial updates, and DELETE for removal. Return 201 for successful creation and 204 for deletions.

REST suits resource-oriented services with standard CRUD operations and simple caching, while GraphQL lets clients request exactly the fields they need through a single typed endpoint. GraphQL requires DataLoaders to avoid N+1 queries and complexity limits to prevent expensive queries.

Use the DataLoader pattern to batch and cache database requests per request cycle. A DataLoader collects all IDs requested during field resolution and fetches them in a single query, mapping results back to the original order.

URL versioning like /api/v1/users is recommended because it is explicit and easy to route. Header versioning keeps URLs clean but is less visible, while query parameter versioning is easy to test but can be forgotten by clients.

Use cursor-based pagination (Relay-style with edges and pageInfo) for large or frequently changing datasets and infinite scroll interfaces. Offset pagination with page and page_size parameters is simpler and works well for small, stable collections.

Common pitfalls include using verbs in URLs, ignoring HTTP semantics like making POST idempotent, inconsistent error formats, missing rate limits, deep resource nesting beyond two levels, and mirroring the database schema directly in the API structure.