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.

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.

Resource & URL modeling

Resources are nouns; HTTP methods are the verbs. Never put a verb in a path.

Rules, each with its reason:

• Plural collections, consistent everywhere — /projects, /projects/{id}. Pick plural and never mix singular in; inconsistent naming is the most-cited design smell.
• Nest sub-resources one level — /projects/{id}/tasks. Deeper than one level (/projects/{p}/tasks/{t}/comments/{c}) gets unreadable; link to the flat resource instead (/comments/{c}).
• Methods carry intent — GET read, POST create, PUT full replace, PATCH partial update, DELETE remove. A path never says what it does.
• Filter/sort/select via query string, not new paths — ?status=open&sort=-created_at&fields=id,title. One GET /projects handles all of it; don't mint /projects/open and /projects/byDate.

Full query grammar (filter operators, sparse fieldsets, sort syntax), content negotiation, rate-limit headers and a HATEOAS note: references/rest-conventions.md.

Status codes that matter

You need a small map, used consistently. Don't overload 200.

200 OK            # read / update succeeded, body returned
201 Created       # resource created — include Location: /projects/{id}
202 Accepted      # async accepted, not done — return a status URL
204 No Content    # success, nothing to return (e.g. DELETE)
400 Bad Request   # malformed syntax / unparseable
401 Unauthorized  # not authenticated — who are you?
403 Forbidden     # authenticated but not allowed — I know you, no
404 Not Found     # resource absent (or hidden from this caller)
409 Conflict      # state collision — duplicate, version mismatch
422 Unprocessable # syntactically fine, semantically invalid (validation)
429 Too Many Req  # rate limited — include Retry-After
5xx               # your fault, never the client's; never leak the stack

Two distinctions agents get wrong:

• 401 vs 403 — 401 means unauthenticated (no/invalid credentials); 403 means authenticated but unauthorized. Returning 401 on a permission failure leaks that re-auth might help when it won't.
• 409 vs 422 — 409 is a state conflict (the request fights the current server state: dup key, stale version). 422 is a content problem (the body parses but fails business rules). Full status-code table with when-each in references/rest-conventions.md.

Error envelope: RFC 9457

One error shape across every endpoint. Adopt RFC 9457 Problem Details (the current standard; it obsoletes RFC 7807). Media type application/problem+json. Standard members: type, title, status, detail, instance, plus your own extension members.

{
  "type": "https://api.acme.com/problems/validation-error",
  "title": "Your request parameters didn't validate.",
  "status": 422,
  "detail": "due_date must be in the future.",
  "instance": "/projects/8a3/tasks",
  "errors": [
    { "field": "due_date", "message": "must be in the future" }
  ],
  "correlation_id": "req_01H..."
}

Rules:

• type is a stable, machine-readable URI — clients branch on it, not on detail. Never change a type string once published.
• title is human, generic per type; detail is human, specific to this occurrence. detail is for people, not parsers.
• Always carry a correlation/request id (extension member) so a support ticket maps to a log line.
• Never leak internals — no stack traces, SQL, internal hostnames, or raw DB ids in detail. That is both an information leak and a coupling leak.

Pagination

Default to cursor (keyset) pagination. Use offset only for small, bounded sets.

Decision line: if the list can grow unbounded or rows can be inserted between page fetches, use cursor.

REST cursor envelope — same keys on every list endpoint:

{
  "data": [ { "id": "...", "title": "..." } ],
  "next_cursor": "eyJpZCI6MTI4N30",
  "has_more": true
}

The next page is GET /projects?cursor=eyJpZCI6MTI4N30&limit=50. The cursor is opaque — clients must not parse or construct it.

GraphQL has its own de-facto standard: Relay Connections — edges { node, cursor }, pageInfo { hasNextPage, endCursor }, args first / after. Use it; don't invent a bespoke GraphQL pagination shape. See references/graphql-design.md.