Use the smallest set of status codes necessary. Consistency beats completeness.

A note on 400 vs 422: both are used for validation errors. 400 is more common, 422 is technically more correct for semantically invalid input that is syntactically valid. Pick one and be consistent — mixing them confuses clients.

RFC 7807: Problem Details for Error Responses

The table above says which code to return; it says nothing about the shape of the error body, and every API in practice invents its own — { "error": "..." }, { "message": "..." }, { "errors": [...] } — forcing client code to special-case error parsing per API it talks to.

RFC 7807 standardizes this as application/problem+json:

• type — a URI identifying the error kind. It doesn't need to resolve to anything; it's a stable identifier clients can branch on, more specific than the HTTP status alone.
• title — a short, human-readable summary, constant for a given type.
• status — the HTTP status code, duplicated in the body for clients that inspect the body without reading headers.
• detail — a human-readable explanation specific to this occurrence.
• instance — a URI identifying this specific occurrence, often just the request path.

Clients that don't know about RFC 7807 still work fine — it's just JSON with a few conventional field names. Clients that do can branch on type reliably instead of pattern-matching detail strings, which change wording over time.

Telling Clients When to Retry: Rate-Limit Headers

The table above lists 429 Too Many Requests with no guidance for the caller on what to do next. A bare 429 tells a client it was rejected; it doesn't say when trying again might succeed — without that, a client's only options are guessing a backoff or retrying immediately and getting rate-limited again.

• Retry-After — seconds (or an HTTP date) until the client should retry. Standardized (RFC 9110), understood natively by some HTTP clients.
• X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — not standardized, but a de facto convention (GitHub, Stripe, and Twitter all use variants) that lets a well-behaved client throttle itself before ever hitting 429, by watching X-RateLimit-Remaining drop and backing off proactively.

Sending X-RateLimit-* on successful responses too — not only on the 429 itself — is what lets clients self-throttle ahead of the limit instead of only reacting after being rejected.

---

API Versioning Strategies

APIs change. Versioning lets you make breaking changes without breaking existing clients.

Strategy 1: URL versioning — most common, most visible:

Pros: obvious, easy to test in browser, easy to route at the load balancer. Cons: URLs are supposed to identify resources, not API versions.

Strategy 2: Header versioning — cleaner URLs:

Pros: clean URLs. Cons: harder to test, often stripped by proxies.

Strategy 3: Content negotiation:

Accept: application/vnd.myapi.v2+json

Used by GitHub and Stripe. Most expressive, most complex.

The pragmatic choice: URL versioning (/v1/, /v2/) for public APIs. Header versioning for internal APIs. Start with /v1/ from day one — retrofitting versioning is painful.

What counts as a breaking change:

• Removing or renaming a field in a response
• Changing a field's type
• Removing an endpoint
• Changing authentication requirements
• Making an optional field required

What is NOT a breaking change:

• Adding new optional fields to responses
• Adding new optional query parameters
• Adding new endpoints

---

Pagination: Offset vs Cursor

A cursor is a bookmark in a paperback — no matter how many pages someone else adds to the front of the book, your bookmark reliably picks up exactly where you left off. Offset pagination is memorizing "page 43" — add a page up front and you re-read a paragraph or skip one entirely.

Offset pagination — simple but has problems at scale:

Problems:

• Page drift: if an item is inserted while paginating, page 3 starts one record later — items get skipped or duplicated.
• Performance: SELECT ... OFFSET 10000 forces the database to scan and discard 10,000 rows.

Cursor pagination — solves both problems, harder to implement:

A single-field cursor (id < cursor.id, sorted by id alone) only produces a stable order when the sorted field is itself unique. The moment sorting is exposed as a client-facing option — sort=-createdAt, sort=title from the filtering section above — a plain { createdAt: { lt: cursorValue } } breaks: two posts can share a createdAt timestamp or a title, and rows tied on that value get silently skipped or repeated across pages. Cursor pagination and arbitrary sorting only work together with a compound cursor — the sort field plus a unique tie-breaker (id), both encoded in the cursor and both used in the comparison:

A compound cursor is only fast if the database has a matching compound index to seek on — index (sortField, id) for every field you actually allow sorting by, not just (id). This is also why sortField is validated against SORTABLE_FIELDS rather than accepted as free text: an unindexed or arbitrary column both defeats the performance point of cursor pagination and (if it ever reached a raw query builder instead of Prisma's parameterized where) would be an injection risk.

Cursor pagination is O(1) at any depth and is immune to page drift. Use it for feeds, activity streams, and any large dataset. Offset pagination is fine for admin UIs with small datasets where users need to jump to a specific page.

---

Filtering, Sorting, and Field Selection

Standard query parameter conventions:

---

OpenAPI 3.0 Documentation

OpenAPI (formerly Swagger) is the standard for describing REST APIs. A valid OpenAPI spec generates interactive documentation, client SDKs, and test mocks.

Defining the spec

Annotating routes with JSDoc

Serving Swagger UI

Visit http://localhost:3000/docs — interactive documentation where you can send real requests.

---

ETag Caching

ETags let clients avoid downloading unchanged resources:

---

Summary

• URLs are nouns, methods are verbs. /users/42 is the resource; DELETE /users/42 is the operation. Verbs in URLs are a design smell.
• HATEOAS is the specific "uniform interface" sub-constraint almost every API skips — links in the response describing valid next actions, discovered rather than memorized from docs.
• Limit nesting to two levels. Deeper nesting is hard to maintain. Prefer top-level resources with filter params over deep nesting.
• PATCH for partial updates, PUT for full replacement. PATCH is almost always what you want.
• Idempotency matters for reliability. GET, DELETE, and PUT should be safely retryable. An Idempotency-Key header makes POST safely retryable too — essential once a client can't tell a lost response from a failed request.
• URL versioning (/v1/, /v2/) is the pragmatic choice. Start with /v1/ on day one.
• RFC 7807 Problem Details standardizes the error body shape (type/title/status/detail); rate-limit headers (Retry-After, X-RateLimit-*) tell clients when a 429 is worth retrying.
• Compound cursor pagination (sort field + id tie-breaker) for large datasets and feeds where sorting is client-selectable — a single-field cursor breaks the moment the sorted field isn't unique. Offset pagination for small admin datasets where jumping to page N matters.
• OpenAPI 3.0 spec + Swagger UI = interactive docs your API consumers can use immediately. Generate from JSDoc comments in route files — documentation stays co-located with the code.

Next: GraphQL with Apollo Server — schema-first API design, queries, mutations, subscriptions, the N+1 problem and how DataLoader solves it, and when GraphQL is the better choice over REST.

---