01
API-first, in name
Software is one of the largest investments a modern company makes, and the way its interfaces are designed shapes how fast that investment pays back. Ask most engineering organisations, and they will tell you they are API-first. Look at how they work, and a different picture appears: the code is written first, and the specification is generated from it afterwards — if at all.
| Indicator | Level | What it means |
|---|---|---|
| Strictly design-first SmartBear 2020 | 23% | Teams that always write the contract before the code |
| Hybrid SmartBear 2020 | 28% | Contract first on some projects, code first on others |
| Use OpenAPI SmartBear 2020 | 82% | The format is everywhere — which hides how it is used |
| Call themselves API-first Postman 2025 | 82% | Intent, including tooling, testing and governance |
| Fully API-first Postman 2025 | 25% | API product management and contract-first truly embedded |
| Run contract tests Postman 2025 | 17% | Automatically check that the code still matches the contract |
The gap shows up in people’s weeks. In Postman’s 2025 survey, 69% of developers spend more than ten hours a week on API work, and 93% of API teams hit recurring collaboration blockers — mostly inconsistent documentation (55%) and duplicated work (35%). Lots of specifications, little contract-first discipline: the specs are being written after the fact, which forfeits most of what made contract-first worth doing.
02
What code-first quietly costs
When the contract comes after the code, teams lose things they rarely see on a dashboard:
Front-end, mobile, QA and integration teams wait for the back end, instead of building against a stable contract and mocks from day one.
Business people and API consumers can’t check the data and the flow until money has already gone into the implementation.
Contracts generated from code tend to expose database schemas and framework quirks instead of what consumers need.
Without a contract, it’s hard to tell an intended change from a bug — and constant interface churn wears down trust between teams.
A contract lets the back end change its storage, framework or language without breaking anyone.
A trusted spec can generate client SDKs, server stubs, mocks, documentation and contract tests.
Designed APIs become products other teams can find and reuse; code-first endpoints stay single-purpose.
Naming, authentication and breaking-change rules can be checked in CI — before an outage, not after.
03
Why teams skip it anyway
Nobody chooses code-first because they think it’s better. They choose it to avoid what we can call the authoring tax: the immediate cost of writing the contract first.
- The blank page. Writing a specification from scratch means modelling the business domain and its data before anything runs.
- OpenAPI is hard to write by hand. Verbose YAML or JSON is tedious and error-prone; even teams that believe in it, like Microsoft ISE before moving to TypeSpec, find manual authoring becomes a bottleneck.
- It feels slow. Code-first gives instant gratification; contract-first feels like paperwork to the person doing it.
- Keeping it in sync. A hand-written spec drifts from the code unless CI compares them — and without that, nobody trusts it.
- Versioning and tooling. Breaking changes, fragmented tools and rigid generators make maintaining the design artifact more work than generating it from code.
- Weak payoff for internal services. When the same team writes both sides, the coordination benefit feels smaller than the tax.
04
Putting a price on it
“Developer drag” doesn’t move a budget. Four cost buckets do — each with a formula a finance team can fill with real data:
| Cost bucket | How finance sees it | What drives it |
|---|---|---|
| 1 · Rework & coordination | Lost capacity = headcount × loaded cost × share of API work × share lost to friction | Spec/code drift, manual interface updates, duplicated code, reconciliation meetings |
| 2 · Delayed time to market | Deferred margin = monthly gross profit of the capability × months of delay | Serial handoffs; front-end and mobile waiting for back-end code |
| 3 · Partner & integration onboarding | Onboarding cost + deferred partner revenue | No reliable mocks, custom integration logic, manual schema checks |
| 4 · Maintenance & technical debt | Loaded cost × share of time on maintenance and defects | Schema drift, exposed internal models, governance fixes after deployment |
For a sense of scale: Stripe’s Developer Coefficient study found that of a 41.1-hour developer week, 13.5 hours go to technical debt and 17.3 hours to maintenance work like debugging and refactoring. The Consortium for Information & Software Quality put the 2022 cost of poor software quality in the United States at $2.41 trillion, with technical debt at about $1.52 trillion.
05
A worked example
Take an engineering organisation of 40 people at a fully loaded €120,000 each — a €4.8 million budget — spending 45% of its time on API work. Assume, conservatively, that just 10% of that API time is lost to avoidable friction: writing specs by hand, fixing drift, resolving mismatches, duplicating code.
€4,800,000 × 45% × 10% = €216,000 a year
Now add one customer-facing capability expected to earn €250,000 a month in contribution margin, delayed by just one month by serial handoffs, missing mocks and late interface redesigns:
€250,000 × 1 month = €250,000 deferred
That is €466,000 — before counting partner onboarding or long-term maintenance at all. The point isn’t the number; it’s replacing a vague complaint with inputs anyone can check.
Three questions for the finance conversation
- Capacity: what share of engineering payroll goes into reconciling, translating and repairing interface decisions already made elsewhere?
- Margin: how much contribution margin is deferred while consumer teams wait for back-end code before contracts are final?
- Redundancy: how many duplicate components and endpoints are funded because nobody could find a contract they trusted?
06
Removing the tax
If the tax is what pushes teams back to code-first, the answer isn’t stricter mandates. It’s making the tax disappear: stop writing contracts by hand, and let them be projections of the domain model the business already agrees on.
- Domain storytelling
- Event modelling
- OpenAPI contract, derived
- SDKs · stubs · mocks · contract tests
- No blank page. The interface is designed while the domain is being modelled — nobody writes YAML from scratch.
- Nothing to keep in sync by hand. Business rules, boundaries and event structures flow into the developer’s artifacts directly.
- All the benefits, none of the paperwork. Every team gets a stable, consumer-oriented contract early — without a new burden on engineering.
What to do next
- Change what governance measures. Instead of buying more API-management tooling or issuing mandates, aim at removing the manual authoring tax.
- Measure the loss. Ask engineering managers for a baseline: hours lost to spec reconciliation, integration waits and drift fixes.
- Pilot on one domain. Apply model-to-contract projection on one high-impact, cross-team boundary, prove the capacity and time-to-market gains, then scale.
Contract-first is a capital-allocation decision. Remove the authoring tax, and the capacity, quality and speed follow — without the paperwork.
