api-contract-design

API Contract Design

An API is a promise. Clients — your own frontend, partners, and AI models writing integrations — build on exactly what you return, including your mistakes. Design every endpoint as if you can never change it, because for practical purposes you can't (only add).

Contract-first, always

Before writing the handler, write the contract: method, path, auth, request shape, response shape, every error case with its code. Five minutes of contract prevents the frontend and backend from building two different APIs. Keep it wherever it's enforceable — OpenAPI, typed schemas (Pydantic/zod), or at minimum a markdown table — the schema layer IS the documentation if you make it one.

Shape rules

• Resources and predictability over cleverness: plural nouns (/invoices/{id}), nesting only one level deep when ownership is intrinsic (/invoices/{id}/payments); verbs only for true actions (/invoices/{id}/cancel). A developer should guess the next endpoint correctly.
• Response envelopes are uniform across the whole API: pick one success shape and ONE error shape ({"error": {"code", "message"}}-style) and never deviate. Machine-readable code (stable, documented, for programs) + human message (for humans, changeable). Clients that parse message strings are a bug you caused.
• Every list endpoint, from day one: pagination (limit + cursor/offset), a deterministic default sort, and filters as query params. Retrofitting pagination onto a client that assumes "all rows" is a breaking change.
• Field conventions fixed project-wide: one case style, ISO-8601 timestamps in UTC, money as string-decimal or integer minor units (never JSON floats), booleans not 0/1 strings, null vs absent given meaning consistently.
• Return the resource state after mutation (the created/updated object), so clients don't need a follow-up GET.

Status codes — the short honest set

200 read/update ok · 201 created · 204 deleted/no body · 400 malformed/validation · 401 who are you · 403 you can't do that (but see threat-model-security: prefer 404 when existence itself is private) · 404 not found or hidden · 409 state conflict (duplicate, already-cancelled) · 422 semantic validation if you distinguish it · 429 rate limited · 5xx our fault, never leaks internals. Don't return 200 {"success": false} — that lies to every HTTP-aware layer between you and the client.