Spec-First Development
also called Design-First
Writing and reviewing the API specification before implementing, so the contract is designed deliberately rather than emerging from code.
The alternative, generating the specification from annotations in the implementation, is less effort and guarantees the document matches the code. It also means the contract is whatever the implementation happened to produce — including field names that leak internal models, inconsistent error shapes, and resources shaped by the database schema.
Spec-first inverts it: the specification is written, reviewed by consumers, and then implemented against. The review is the point, because it happens when changing the design costs nothing.
It also unblocks parallel work — consumers generate clients and mock servers from the specification and build immediately, rather than waiting for the provider.
The cost is drift: the specification and implementation can diverge unless something checks. The fix is contract validation in CI, asserting the implementation matches the specification, and request or response validation at the gateway.