Skip to content
Documentation

API-first

A component’s API is what everyone else depends on. Design it first, agree it first, and treat the implementation behind it as replaceable.

What it means in practice

Section titled “What it means in practice”
  • The contract is written before the code, and reviewed by the people who will call it — not derived from an implementation that already shipped.
  • Generated code flows one way: clients and server stubs come from the specification. A hand-edit to generated output is a bug in the spec.
  • The interface outlives its implementation. If rewriting a service forces its callers to change, the boundary was drawn in the wrong place.

Why first, and not eventually

Section titled “Why first, and not eventually”

An API extracted after the fact describes whatever the implementation happens to do, including the parts nobody meant to promise. Once a caller depends on it, the accident is load-bearing. Writing the contract first is the cheapest moment to notice that the boundary is wrong.

Where it is enforced

Section titled “Where it is enforced”

In api-hub: contracts are parsed, validated and scored on submission, and a revision is registered only once it passes. That makes API-first a gate rather than a good intention — see contracted design.