API-first in practice: what changes when the spec is the source of truth

"API-first" has been diluted into meaning roughly "we take our API seriously". Useful as a value, useless as a decision.

The version that changes anything is narrower: the specification is an input to your build, not a description produced afterwards. Everything else people mean by the term follows from that or does not matter.

The three arrangements

Code-first with a hand-maintained spec. You write the service, then you write a document that describes it. This is the most common arrangement and the only one where drift is guaranteed rather than possible, because keeping them in step is a separate task with no forcing function. The 2026 data has 41% of APIs drifting within thirty days, and this is mostly what it is measuring.

Code-first with annotations. Decorators in your handlers produce the document. Drift in the shape mostly goes away because the spec comes from the types. What you get instead is a document that is structurally complete and semantically empty: every field present, no descriptions, responses typed object, no examples. It satisfies a validator and generates a poor client and a worse documentation page.

Spec-first. The document is written or designed first, and the server is checked against it or generated from it. Drift is structurally prevented because the code cannot compile away from the contract.

The interesting thing is that the second and third are not as far apart as the debate suggests. An annotated codebase where someone also writes the descriptions, the examples and the error responses produces a document as good as a hand-designed one. The failure is not the annotations, it is stopping when the types are covered.

What actually changes day to day

Reviewing an API change becomes possible. When the spec is in the pull request, a reviewer can see that an operation gained a required parameter before it ships. That is the single biggest practical gain and it needs no tooling beyond the diff.

The spec becomes the thing you argue about. Naming, resource shape and error format get discussed while they are cheap to change, rather than after three clients depend on them. This is where most of the value is, and it is a habit rather than a tool.

Parallel work stops being a coordination problem. A frontend team can mock against the document while the service is being built. This is the benefit people lead with and it matters less than the review one, because in practice most teams working this way were already coordinating fine.

Everything downstream stops being maintained by hand. Documentation, client libraries, mock servers, contract tests, agent tools. Each of those is either generated from the document or maintained separately, and separately means drifting.

The cost, honestly

Spec-first is slower at the start, and the slowdown is real rather than a mindset problem.

You are designing before you know the shape, and some of what you design will be wrong in ways you only discover during implementation. Editing a spec and then editing code is two steps where code-first is one. For a prototype, or an API with one internal consumer that you will rewrite in a month, that overhead buys nothing and skipping it is correct.

The overhead pays back when the number of things derived from the document goes up: more languages, an external audience, agent tooling, a docs site somebody outside your team reads. Below that threshold, a good annotated spec is the pragmatic answer and there is no need to be religious about it.

The property that actually matters

Whichever route, one test tells you whether it is working:

Can the document and the running API disagree without anything failing?

If yes, they will, on roughly the schedule the drift data describes. If no, you have the property that makes everything else safe, and how you got there is an implementation detail.

Ways to get there, cheapest first: validate real responses against the schema in CI, gate pull requests on a semantic spec diff, generate the server types from the document, or generate the handlers outright. Any forcing function beats none.

What to do about the document you already have

Most teams reading this are not starting fresh. They have a spec of uncertain quality and a service that has moved past it.

The order that works:

Find out what state it is in. Not whether it validates, which tells you almost nothing, but whether the things downstream of it can be built. Do operations have prose, do responses declare schemas, do parameters have descriptions, are failures declared.

Fix the heavyweight gaps first. Missing response schemas and undeclared errors block more than anything else, because they are what turn a generated client from typed into untyped.

Then add the forcing function, so the work you just did does not decay.

Then start deriving things from it. Docs, clients, tools. Deriving from a bad document produces bad output and teaches everyone the approach does not work.

That first step is what our spec audit is for: it scores a document out of ten against the fourteen rules that decide what can be generated from it, names the operations failing each one, and publishes the whole rule table so you can act on it without us. Free, no account, and the spec is not stored.

Once the document is in shape, Octri is what derives the rest from it: reference documentation, client libraries in ten languages, an MCP server for agents, all rebuilt when the spec changes so none of them can drift away from it.