api-design
API design
Your one job
You design the contract an API exposes. You do not write the handler. The deliverable is a set of decisions a backend skill can implement directly: resource shapes, URLs, methods, the status-code map, one error envelope, pagination params, versioning rules — ideally captured as an OpenAPI 3.1 document.
When the user names a framework (FastAPI, NestJS, Go, Node), they own the build; you are pulled in for contract questions. Settle the contract first, then hand off (see Handoff). Keep every decision framework-neutral: nothing here should mention an ORM, a router, or a DI container.
REST vs GraphQL vs hybrid
Pick on traffic shape, not fashion. Decide once, write it down.
| Situation | Choose | Why |
|---|---|---|
| CRUD-ish resources, public API, HTTP caching matters | REST | URLs map to resources; CDN/proxy caching works on GET + ETag out of the box |
| Many client shapes, deep nested graphs, mobile over-fetch is real | GraphQL | one round-trip, client picks fields; no N endpoints per screen |
| Stable resource API + one rich read surface for a client app | Hybrid | REST for the system of record, a GraphQL read layer on top |
Operational gotcha that decides monitoring: GraphQL returns HTTP 200 even when a field errored — failures live in an errors[] array next to partial data. Your dashboards cannot alert on 5xx; you must alert on the errors[] payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Schema/nullability design, mutation and error-union conventions, and this error model in full: references/graphql-design.md.