api-design

name	api-design
description	Use when designing or reviewing an HTTP/RPC API surface — resource modeling, pagination, error envelopes, versioning, idempotency. Falsifiable contracts, not style preferences.

API Design

Rules for any API another team, service, or future-you will call. Every rule here is checkable in review.

Resources

• Nouns, not verbs: POST /orders, not POST /createOrder. Verbs allowed only for true actions with no resource representation (POST /orders/{id}/cancel).
• One resource, one canonical URL. Aliases and "convenience" routes multiply cache keys and auth checks.
• Nested paths max two levels (/orders/{id}/items). Deeper nesting means the child deserves a top-level resource.

Pagination

• Cursor-based for any dataset that mutates or can exceed ~10k rows. Offset pagination on mutable data skips/duplicates rows mid-scroll — that is a bug, not a style choice.
• Offset is acceptable for small, effectively-immutable datasets (admin lists, lookups).
• The cursor is opaque to clients (base64 of sort key + id). Documenting its internals turns it into API surface.
• Every list response carries next_cursor (null = end). No "call until empty page" contracts.

Errors

• One error envelope repo-wide, RFC 7807 shape: { "type", "title", "status", "detail", "instance" }. A second error shape anywhere is a BLOCK in review.
• Machine-readable type (stable URI/slug), human-readable detail. Clients branch on type, never parse detail.
• 404 vs 403 leak rule: if the caller may not know the resource exists, return 404 for both missing and forbidden. Returning 403 confirms existence.
• Validation failures: 422 with a per-field errors array inside the envelope, not the first error only.

Versioning

• Additive-only within a major version: new optional fields and new endpoints are safe; renaming, retyping, or removing anything is breaking.
• Breaking change ⇒ new major path (/v2/) + deprecation window on v1 with a Sunset header and a dated removal plan. No silent behavior changes.
• Never version individual fields or negotiate versions via optional headers — one axis of versioning only.

Idempotency & semantics

• Every non-GET mutation a client may retry (payments, order creation, webhooks) requires an Idempotency-Key header; same key + same body replays the stored result, same key + different body returns 409.
• PUT is full replace, PATCH is partial. In PATCH, absent field = unchanged, null = clear. Document it once, follow it everywhere (omission-preserves-stale-state bugs live here).
• GET/HEAD never mutate. No "GET with side effects" even for convenience.

Conventions

• Timestamps: UTC, ISO-8601 with offset (2026-07-05T10:00:00Z). Epoch integers only in high-volume telemetry.
• IDs in responses are strings, even when numeric today — retyping later is a breaking change.
• Field naming picks one case (snake_case JSON) and never mixes.

When NOT to apply

Internal one-consumer endpoints you can change atomically with the caller can skip versioning ceremony and idempotency keys — say so in the handler comment. The error envelope and 404/403 rules still apply.