api-design-rest-graphqllisted

# API design: REST & GraphQL An API is a contract with every caller you'll never meet. Design the contract before writing the handler — retrofitting pagination, versioning, or error shape onto a shipped endpoint breaks every existing consumer. ## 1. Resource modeling (REST) - Model **nouns**, not actions: `/orders`, not `/getOrders` or `/createOrder`. The HTTP verb carries the action. - Collections are plural (`/users`), a single resource is the collection + identifier (`/users/42`). Nest only for true ownership (`/users/42/orders`), never to express a query — query params do that (`/orders?userId=42`). - Keep resource shape stable across an endpoint's lifetime; add fields, don't repurpose them. ## 2. HTTP status discipline | Code | Use for | |---|---| | 200 | Success with body | | 201 | Created — return the resource + `Location` header | | 202 | Accepted — async processing started | | 204 | Success, no body (e.g. DELETE) | | 400 | Malformed request (client's fault, fixable by changing the request) | | 401 | No/invalid credentials | | 403 | Authenticated but not authorized | | 404 | Resource doesn't exist (or, deliberately, exists but hidden from this caller) | | 409 | Conflict — state clash (duplicate create, version mismatch) | | 422 | Semantically invalid (well-formed but violates business rules) | | 429 | Rate limited — pair with `Retry-After` | | 500 | Unhandled server fault — never leak internals in the body | | 503 | Dependency down / overloaded — pair wit