API Contract Design

An API is a promise enforced by other people's code. The cost of a bad contract is paid forever by every caller; design for the version you cannot recall.

Model the contract as four coupled surfaces

1. Shape: types, required vs optional fields, nullability, enums (open vs closed).
2. Semantics: what each call means, idempotency, ordering guarantees, side effects, consistency level.
3. Failure: every error the caller must distinguish, retriability, partial-success behavior.
4. Evolution: what can change without breaking callers, and how clients discover capabilities.

A change is "compatible" only if it is safe across all four — a field that is shape-compatible can still be semantically breaking.

Compatibility rules that actually hold

• Adding an optional field: safe. Making an optional field required: breaking.
• Widening an accepted input: safe. Narrowing output guarantees: breaking.
• Closed enums break when you add a variant clients must handle; prefer open enums + documented "unknown" handling.
• Default values are part of the contract. Changing a default is a silent breaking change.
• Tightening validation breaks existing valid-but-sloppy callers. Loosen freely, tighten via new version.

Failure semantics (the part most designs skip)

• Make idempotency explicit: which calls are safe to retry, and is there an idempotency key?
• Distinguish retryable (5xx, timeout) from terminal (4xx) at the type level so clients don't retry into duplication.
• Define partial success precisely — batch endpoints must say which items succeeded, not just "200 OK".
• Errors are an API. Stable codes + machine-readable detail beat prose messages clients will regex.

Adversarial validation

• A hostile client sends nulls, unknown enum values, huge payloads, out-of-order calls, and double-submits. Does the contract still have defined behavior?
• A future you adds a feature. Does the schema have room, or does it force a v2?
• Two clients on different versions hit the same backend. Does data written by one corrupt the view of the other?
• Network dies mid-request. Can the client tell whether the write happened?

Non-obvious tradeoffs

• Versioning strategy (URL vs header vs field-level) trades discoverability against routing complexity; field-level evolution usually beats hard version cuts.
• Rich, nested responses reduce round-trips but couple clients to internal structure — every field you expose is a future migration constraint.
• Strong typing at the edge (codegen) catches shape breaks but can mask semantic breaks that look type-identical.

Output structure

Deliver: the contract (typed schema), an explicit compatibility statement (what's frozen vs evolvable), the full error taxonomy with retriability, and a migration path for the next likely breaking change.