API-first is not a slogan about microservices. It is a publishing order: the interface contract is reviewed before implementation starts. Roy Fielding’s dissertation defined six resource-oriented constraints. OpenAPI 3.x is how most teams write those constraints down. This page is a decision record: when to version, what a breaking change is, and how a five-person team rolls back without a platform cult.

3OpenAPI 3.x familyCurrent widely shipped major line
6Fielding REST constraintsArchitectural constraints in the dissertation
4Breaking-change typesRemove or rename a field, tighten a type, change auth or pagination defaults
Cited figures used in this edition

Publish the contract first

Write the OpenAPI document, review error shapes with the consumer, and freeze the happy path before a sprint of handlers. Fielding’s six constraints are a test: is the interface resource-oriented, or is it a remote procedure call wearing a URL?

A reviewable contract includes request and response schemas, authentication, status codes, idempotency expectations, and concrete examples. A path list without failure behavior still forces consumers to discover the real contract from running code.

API-First Means the Contract Ships Before the Code
Breaking-change types to version

What counts as a breaking change

Removing or renaming a field, tightening a type, changing authentication, or changing pagination defaults are breaks. Adding an optional field is usually not. If you cannot say which bucket a diff is in, you are not ready to deploy.

Even an additive field can break a strict client that rejects unknown properties, so compatibility must be tested against actual consumers. Documentation-only wording, a new optional endpoint, or a broader accepted input is normally non-breaking when observable behavior stays compatible.

API-First Means the Contract Ships Before the Code
  • Remove a field4 score
  • Rename a field3 score
  • Tighten a type2 score
  • Change auth5 score

OpenAPI (2026-08). Illustrative severity scores for break types a startup API must version — not measured frequencies.

Worked versioning for a five-person team

Keep /v1 until a break. Ship /v2 as a parallel route for one billing cycle. Date the deprecation. Do not rename folders as a substitute for a version. A Mashhad team integrating a local payments provider should version the payments resource independently of the user resource so a bank-API change does not rewrite login.

For a second example, replacing a string status with a closed enum can reject values an existing mobile build still sends. Keep v1 accepting the old shape, publish the v2 enum with migration examples, and remove v1 only after telemetry shows the old client has left the supported window.

Rollback is part of the contract

If you cannot restore the previous contract — handlers and the last released schema — you do not have an API-first system. You have a hope. Store the last released OpenAPI file next to the runbook. Rollback that omits the schema is not rollback.

Database changes must respect the same boundary: deploy additive storage first, then readers, then writers, and remove old fields later. A handler rollback cannot help if an irreversible migration already destroyed the representation v1 needs.

When API-first is the wrong order

A weekend prototype with one consumer sitting next to you can be code-first. The moment a second team or a mobile build depends on the shape, freeze the contract. Do not wait for a platform hire.

Internal exploratory code that is discarded before another process depends on it does not need a public compatibility promise. The boundary is dependency, not company size: a monolith endpoint used by one shipped client already has a contract. Microservices are not required for API-first.

Frequently asked questions

Do I need microservices to be API-first?

No. You need a reviewed contract. A modular monolith can be API-first.

OpenAPI or GraphQL?

Pick the one your consumers can freeze. GraphQL still needs a version and a breaking-change policy.

When do I increment the URL version?

On a breaking change you cannot otherwise hide. Not on every commit.

What is the rollback drill?

Restore the last OpenAPI schema, redeploy the last handlers, and tell consumers the window.

Answers to the questions this topic usually leaves hanging.

How we sourced this

Every statistic in API-First Means the Contract Ships Before the Code is attributed. Where a number is an estimate rather than a census, the note says so.

  1. Roy Fielding, REST dissertationArchitectural constraints for resource APIs.
  2. OpenAPI InitiativeCurrent specification line for HTTP APIs.
  3. Google API Improvement ProposalsPractical versioning and compatibility rules.
  4. Microsoft REST API guidelinesCompatibility and error-shape conventions.

Primary sources used for this edition.

The bottom line

Ship the contract, version the break, keep last week’s spec in the runbook.

If you want the adjacent decisions after API-First Means the Contract Ships Before the Code, start with Architecture patterns, Microservices, Scalability planning, DevOps.