---
name: api-design
description: "Use when designing the contract of a network API before/independent of implementation — modeling resources and URLs, choosing REST vs GraphQL, picking a versioning strategy, defining one consistent error envelope, and settling pagination/filtering/idempotency conventions. Triggers: 'design the REST API for X', 'what should the endpoints be', 'how do I version this without breaking clients', 'should this be REST or GraphQL', 'cursor vs offset pagination', 'standard error format for my API', 'RFC 9457 problem details', 'idempotency key on POST', '200 with error body', 'diseña la API REST de esto', 'cómo verziono la API sin romper clientes'. NOT implementing endpoints in a framework (that is fastapi/nestjs/go/nodejs), NOT security/auth hardening (that is secure-coding), NOT receiving inbound webhooks (that is webhooks), NOT building an outbound client to a third-party API (that is api-connector-builder)."
tags: [api-design, rest, graphql, openapi, versioning, pagination, http, rfc9457, contract-design]
recommends: [fastapi, nestjs, go, nodejs, secure-coding, webhooks, api-connector-builder, code-review]
origin: risco
---

# 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](#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. Details in `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`.

| Bad | Good | Why |
|---|---|---|
| `POST /createProject` | `POST /projects` | the method is the verb |
| `GET /getUserOrders/{id}` | `GET /users/{id}/orders` | noun hierarchy, no verb |
| `GET /project` and `GET /tasks` | `GET /projects` and `GET /tasks` | one plural convention |
| `GET /projects/active` | `GET /projects?status=active` | filter is a query param |
| `POST /projects/{id}/delete` | `DELETE /projects/{id}` | method, not path segment |

Full query grammar (filter operators, sparse fieldsets, sort syntax) is in `references/rest-conventions.md`.

## Status codes that matter

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

```http
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 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.

```json
{
  "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.

| Approach | Use when | Why |
|---|---|---|
| **Cursor / keyset** | large or changing datasets, feeds, anything hot | opaque token over an indexed ordered column → constant-time, stable across inserts |
| **Offset / limit** | small bounded admin lists, fixed reference tables | simple, but the DB scans-and-discards skipped rows (degrades with depth) and **skips or duplicates rows** when data shifts between page loads |

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:

```json
{
  "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`.

## Versioning & evolution

**Prefer additive, non-breaking evolution over a new version.** A new version forks your client base and your maintenance. Most changes don't need one.

- **Non-breaking (no version bump):** adding an optional field, adding a new endpoint, adding a new optional query param, adding a new enum value clients are told to tolerate.
- **Breaking (needs a version):** removing/renaming a field, changing a type, making an optional field required, changing status-code semantics, changing the error `type` for a case.

When you must version, **use a URL path version (`/v1/...`) for public APIs** — it is visible, cacheable, trivially testable in a browser, and the most common convention clients expect. Header/media-type versioning (`Accept: application/vnd.acme.v2+json`) keeps URLs clean but is harder to test and cache; query-param versioning (`?version=2`) pollutes every URL. Default to path.

Deprecate gracefully with the `Deprecation` and `Sunset` response headers so clients get programmatic warning before removal:

```http
Deprecation: true
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://api.acme.com/v2/projects>; rel="successor-version"
```

Full breaking-vs-non-breaking matrix and the deprecation workflow live in `references/versioning-and-evolution.md`.

## Idempotency & concurrency

- **Make POST/PATCH retry-safe with an `Idempotency-Key` header.** The client sends a unique key; the server replays the original response on a retry instead of double-creating. This is an IETF httpapi draft (not yet an RFC) but is the proven pattern across Stripe, PayPal, and others — adopt it for any create/charge/payment-like operation where a network retry could duplicate work.

```http
POST /payments
Idempotency-Key: 9b1f7c2e-... 
```

- **Use `ETag` + `If-Match` for optimistic concurrency** on PUT/PATCH. The server returns an `ETag` (a version fingerprint) on read; the client sends it back in `If-Match` on write. If it no longer matches, the server returns **412 Precondition Failed** — no lost update. Use `If-None-Match` for conditional GET caching.

## Anti-patterns

| Anti-pattern | Why it bites | Do instead |
|---|---|---|
| Verbs in paths (`/getUsers`, `/createProject`) | duplicates HTTP semantics, breaks caching/tooling | noun + HTTP method |
| Mixed plural/singular collections | clients can't predict URLs | one plural convention everywhere |
| 200 on error (REST) | breaks status-code monitoring and client error handling | real 4xx/5xx + RFC 9457 body |
| Different error shape per endpoint | every client writes per-endpoint parsing | one `application/problem+json` shape |
| Leaking stack traces / SQL / DB ids in errors | info leak + couples clients to internals | generic `title`, safe `detail`, correlation id |
| Offset pagination on a hot/large feed | slow at depth; skips/dups rows on insert | cursor/keyset pagination |
| Unbounded list endpoint (no limit) | one client can pull the whole table | enforce a default + max `limit` |
| New version for every change | forks clients, multiplies maintenance | additive non-breaking evolution |
| Breaking a field in place on a live version | silently breaks existing clients | new field/version + deprecation headers |
| 401 for a permission failure | misleads client into re-authing | 403 when authenticated-but-forbidden |
| 200 for a created resource | hides the create, no `Location` | 201 + `Location` header |
| Ignoring GraphQL partial `errors[]` | failures invisible to monitoring | alert on `errors[]`, not just HTTP 5xx |

## Handoff

The contract is the artifact. Emit it as an **OpenAPI 3.1** document (see `references/openapi-contract.md`) — that is the checkable deliverable a framework skill generates code from.

Hand off to the builder:
- Python/async → [`../fastapi/SKILL.md`](../fastapi/SKILL.md)
- NestJS / Node DI → [`../nestjs/SKILL.md`](../nestjs/SKILL.md)
- Go `net/http` → [`../go/SKILL.md`](../go/SKILL.md)
- Node generally → [`../nodejs/SKILL.md`](../nodejs/SKILL.md)

Adjacent concerns you do **not** own:
- Auth hardening, OWASP, CORS/CSP threat-modeling → [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md) (you only place 401/403/scopes in the contract)
- Receiving inbound webhooks (HMAC verify, replay, dedupe) → [`../webhooks/SKILL.md`](../webhooks/SKILL.md)
- Building an outbound client to a third-party API → [`../api-connector-builder/SKILL.md`](../api-connector-builder/SKILL.md)
- Reviewing handler code (not the design) → [`../code-review/SKILL.md`](../code-review/SKILL.md)

## References

- `references/rest-conventions.md` — full status-code table, filter/sort/sparse-fieldset grammar, content negotiation, rate-limit headers, HATEOAS note.
- `references/versioning-and-evolution.md` — breaking-vs-non-breaking matrix, three versioning mechanisms, deprecation/sunset workflow.
- `references/graphql-design.md` — schema/nullability design, Relay Connections, mutation + error-union conventions, the HTTP-200 error model and its monitoring impact.
- `references/openapi-contract.md` — capture the contract as OpenAPI 3.1 so frameworks generate from it; what `scripts/verify.sh` checks.
