API-First Development: A Practical Guide (2026)

If you build software with more than one person, you have lived this: the frontend developer waits for the backend, the backend changes a field name, and the mobile app breaks on a Friday. API-first development is the habit that stops this. You agree what the API looks like before anyone builds it.

This guide explains the idea in plain words, shows the workflow with a small example we actually ran, and is honest about when it is the wrong tool.

What API-first means, in plain words#

Think of building a house. Code-first is like laying bricks and drawing the plans afterwards from what you built. API-first is drawing the plans, getting everyone to sign them, and then building.

The plan, in software, is an API contract: a file listing every endpoint, what you send, what you get back, which errors can happen and how users sign in. Bump.sh puts it this way: design-first "means you define the API's contract before writing any application code." Postman describes API-first as designing APIs early, before other code, rather than treating them as an afterthought. Swagger describes treating APIs as "first-class citizens."

Several names mean nearly the same thing:

• Design-first, contract-first and schema-first are used interchangeably by Bump.sh and VMware's Tanzu blog.
• Some writers, such as the Stainless guide, use design-first for the contract step and API-first for the whole lifecycle around it. For a team getting started, the difference does not matter.

API-first vs code-first#

Microsoft's engineering playbook compares the two fairly, and it is worth reading both sides.

Neither is "correct." Microsoft's guide says design-first suits externally exposed APIs used by partners, and that code-first is the faster path when requirements change often. Its advice for code-first is to check the generated description automatically so it cannot silently go stale.

Why teams do it: the real benefits#

Vendors write most of the material on this, and that includes the sources we used (Postman, Swagger, Bump.sh and Stainless all sell API tools). So here is what holds up under the sales language:

1. Parallel work. Once the contract exists, a mock server can answer requests the same day. Frontend developers build against the mock while backend developers build the real thing. This is the most repeated and most believable benefit.
2. Fewer misunderstandings. Reviewing a 40-line contract is cheaper than discovering a mismatch in two finished codebases.
3. Consistency. It is easier to enforce naming, error shapes and status codes when they are checked against a rule set before code exists. See our guide to API design principles for what those rules might be.
4. Free by-products. Documentation, client SDKs, test cases and mocks can all be generated from the one file.
5. Safer change. When the contract is in version control, a change shows up as a reviewable diff, and a tool can flag a breaking one.

How common is the approach? In Postman's State of the API survey, 82% of respondents in 2025 called their organization API-first to some degree, against 74% in 2024 and 66% in 2023 (as summarised by Nordic APIs). Two cautions: the 2025 sample was about 5,700 people, much smaller than the 37,000 in earlier years, and the survey is self-reported by people who chose to answer an API survey. Read it as a direction of travel, not proof that API-first works.

A famous story (with a caveat)#

You will often read that Jeff Bezos sent an "API mandate" around 2002: all teams must expose their data and functionality through service interfaces, talk to each other only through them, and design every interface as if outsiders would use it. It is a great story. The caveat: Nordic APIs calls it "tech legend," no original memo is known to survive, and the earliest widely cited source is Steve Yegge's 2011 write-up. Treat it as an illustration of the idea, not a verified historical document.

A sturdier real-world example is Stripe's versioning. Stripe's documentation says that since the 2024-09-30.acacia release it ships new API versions monthly with no breaking changes, and issues a major release with breaking changes twice a year. It also lists what counts as safe: new resources, new optional parameters, new response properties and new event types. That discipline only works when the API is treated as a product with a contract.

The 6-step API-first workflow#

Here is the workflow, kept small enough for a two-person team.

Step 1: Write down who uses the API and what for#

Before any YAML, list the three to five things a caller must be able to do ("get a book," "list books," "add a book"). Swagger's guide suggests listing use cases and drafting potential endpoints with stakeholders first. If you cannot name the caller, you are not ready to design.

Step 2: Write the contract in OpenAPI#

OpenAPI is the standard format for describing an HTTP API. As of this writing, the specification site lists version 3.2.1 (10 September 2026). A document has a few top-level parts: openapi (the version), info (title and version), servers, paths (your endpoints), components (reusable pieces) and security.

Here is a complete, tiny contract for a bookshelf API. We saved it as openapi.yaml and ran every command below against it:

openapi: 3.1.0
info:
  title: Bookshelf API
  version: 1.0.0
paths:
  /books/{id}:
    get:
      operationId: getBook
      summary: Get one book
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
              example: { id: bk_1, title: Dune, author: Frank Herbert }
        '404':
          description: No book with that id
components:
  schemas:
    Book:
      type: object
      required: [id, title]
      properties:
        id: { type: string }
        title: { type: string }
        author: { type: string }

Notice what is already decided: the URL shape, that id is a string, that title always exists but author may not, and that a missing book returns 404. If your team has not met REST yet, read what is a REST API first, and use our guide to HTTP request methods to choose between GET, POST, PUT, PATCH and DELETE.

Step 3: Lint the contract#

A linter checks the contract against rules, like a spell-checker for APIs. Spectral is the common open-source one. Per its README, it lints JSON and YAML and has built-in rule sets for OpenAPI 2, 3.0, 3.1 and 3.2.

echo 'extends: ["spectral:oas"]' > .spectral.yaml
npx @stoplight/spectral-cli lint openapi.yaml

When we ran this on the file above it reported 0 errors and 5 warnings: no servers list, no contact info, no API description, no operation description and no tags. That is exactly the point. It nudges you to finish the contract before anyone depends on it. You can write your own rules (for example, "every path must use plural nouns").

Step 4: Start a mock server#

A mock server reads the contract and pretends to be the real API. Prism, from Stoplight, does this in one command:

npx @stoplight/prism-cli mock openapi.yaml -p 4010

Then call it like the real thing:

curl http://127.0.0.1:4010/books/bk_1
# {"id":"bk_1","title":"Dune","author":"Frank Herbert"}
 
curl -i -H "Prefer: code=404" http://127.0.0.1:4010/books/x
# HTTP/1.1 404 Not Found

We ran both. The first returned the example we put in the contract; the second returned the 404 response because Prism lets you ask for a specific documented status with the Prefer: code= header. Your frontend developer can now build the book page, including the "not found" screen, before a single line of backend exists.

Prism also has a validating proxy mode (prism proxy <spec> <upstream-url>) that checks real traffic against the contract. We did not run that mode.

Step 5: Build the real server against the contract#

Now the backend team builds. Pick any framework (FastAPI, Express, Flask, Spring: the contract does not care). Some teams generate server stubs from the contract, and Microsoft's guide warns that you should first check your chosen generator handles your framework's needs, such as versioning and authentication annotations.

Then test the real server against the contract. Schemathesis reads an OpenAPI schema and generates tests automatically, hunting for server errors, schema violations and validation gaps that hand-written tests miss. We did not run Schemathesis for this post, so check its Quick Start for the current command.

Step 6: Make the contract part of CI#

This is the step most guides skip, and it is where API-first lives or dies. A reader of the original article that inspired this guide asked whether teams stick to the contract under deadline pressure. The answer is to make the pipeline do the policing:

• Lint on every pull request with Spectral.
• Detect breaking changes with a diff tool. oasdiff breaking old.yaml new.yaml compares two versions, and adding --fail-on ERR makes the CI job fail when a breaking change appears. (We summarised this from oasdiff's documentation and have not run it.)
• Test the running server against the contract, since a diff of two spec files cannot catch a server that behaves differently from what the spec says.

Without that last piece you rebuild code-first's biggest problem: a contract that no longer matches reality.

When API-first is the wrong choice#

Be honest with yourself about these cases:

• You are still discovering the product. If requirements change weekly, every change means editing the contract first. Microsoft's playbook says design-first "may not be a good fit" here. Prototype code-first, then write the contract when the shape settles.
• Only one person will ever call it. A solo developer wiring a private backend gains little.
• Your generator cannot express what you need. Test your code generator on a real endpoint before committing.
• You have no review habit. A contract nobody reads is just extra paperwork.

A sensible middle path many teams use: stay code-first while exploring, then freeze the design and go API-first the moment a second team, a partner or a public user depends on you.

An API-first checklist#

• Callers and use cases are written down
• The contract is in OpenAPI and lives in the same repository as the code
• Every operation has a summary, description, tags and at least one example
• Error responses (400, 401, 404) are documented, not just the happy path
• Spectral runs on every pull request
• A mock server is available to the frontend from day one
• A breaking-change check runs in CI
• The real server is tested against the contract, not only against hand-written cases
• A versioning rule exists (for example, date-based like Stripe, or /v1)

Where this leaves you#

API-first development is not a framework or a product. It is an order of work: contract, then mock, then code, with a machine guarding the contract. The biggest gains go to teams where several people or companies depend on the same API. If that is you, start with one OpenAPI file, Spectral and Prism, all free, and you will feel the difference within a sprint.

If you publish an API for others to use, the contract also becomes your storefront. Listing your API where developers can find it, with clear docs and examples, is the natural next step, and that is what the APIHiver marketplace is built for.

Sources#

We read these in October 2026. Several are vendor sites, so we cite them for definitions and mechanics, not for claims that their product is best.

• Bump.sh, Developer guide to API design-first
• Microsoft, REST API design guidance (Code-With Engineering Playbook)
• Swagger, Adopting an API-first approach
• Postman, What is API-first?
• Nordic APIs, A deep dive into the State of the API 2025
• Nordic APIs, The Bezos API Mandate
• OpenAPI Initiative, OpenAPI Specification
• Stoplight, Spectral and Prism
• Schemathesis, documentation
• Stripe, How API versioning works
• Stainless, API-first development: a technical guide for teams
• VMware Tanzu, Understanding API-first development
• Nordic APIs, Using oasdiff to detect breaking changes
• Coder Legion, API-First Development: An Introduction for Modern Developers