API Design Principles — A Field Guide

Good API design is mostly about picking conventions once and applying them everywhere, so a consumer who's learned one endpoint can guess the shape of the next one. The principles below aren't novel — they're the ones that show up, in some form, in every API that's still pleasant to integrate against five years after launch.

Model resources as nouns, not RPC-style actions

A REST-shaped API names endpoints after the things it manages (/orders, /orders/{id}/line-items) and expresses actions through HTTP methods, not verbs in the URL. POST /orders/{id}/cancel is a common and reasonable exception for actions that don't map cleanly to CRUD — but /getOrderById or /updateOrderStatus as separate endpoints signals the API is really RPC wearing REST's clothing, which is fine as a deliberate choice (gRPC, tRPC) but confusing as an accident.

Idempotency keys make retries safe

Network failures mean a client can never be certain whether a POST request that timed out actually succeeded server-side. An Idempotency-Key header (a client-generated UUID, per request) lets the server recognize a retried request and return the original result instead of creating a duplicate — this is the pattern Stripe popularized and it's now close to expected on any payment or order-creation endpoint. Without it, "just retry on timeout" is not a safe instruction to give API consumers.

POST /v1/charges HTTP/1.1
Idempotency-Key: 7d8f2a91-4c3e-4b1a-9e5d-2f8c1a6b3d4e
Content-Type: application/json

{"amount": 2000, "currency": "usd", "customer": "cus_9s6XKzkNRiz8i3"}

# A retried request with the same key returns the original
# response (same status, same body) instead of double-charging.

Cursor pagination over offset for anything that grows

Offset-based pagination (?page=3&limit=20) breaks under concurrent writes — an insert or delete between page fetches shifts every subsequent page's contents, causing skipped or duplicated records. Cursor-based pagination (?after=eyJpZCI6MTIzfQ, an opaque token derived from the last item's sort key) stays consistent regardless of concurrent writes and is what every high-traffic API — Stripe, GitHub, Slack — settled on for exactly this reason.

Error responses need the same design rigor as success responses

A consistent error shape — machine-readable error code, human-readable message, and where relevant a field-level breakdown for validation errors — turns error handling from special-cased guesswork into something a client can branch on programmatically. RFC 9457 (Problem Details for HTTP APIs) standardizes this shape (type, title, status, detail, instance) specifically so clients don't need bespoke parsing logic per API.

Design for additive change from day one

Clients that ignore unknown JSON fields (the common, recommended default) let you add fields without a version bump. The discipline this requires: never repurpose an existing field's meaning, never remove a field without a formal deprecation cycle, and default new optional fields to a value that preserves old behavior. APIs that get this right rarely need a v2; APIs that don't end up maintaining parallel major versions far sooner than planned.

Wrapping up

None of these principles are exotic — idempotency keys, cursor pagination, and structured errors are all well-documented, widely adopted patterns. The value is in applying them consistently across an entire API surface rather than case by case, so a consumer's mental model built from one endpoint transfers cleanly to the next.