API-First Development — why the contract should come before the code

Most APIs are designed by accident. A developer writes a controller, adds some routes, returns whatever the database gives back, and calls it an API. It works — until a second consumer shows up, or the mobile team needs a different shape, or you need to version it, or a partner needs to integrate.

API-First is the discipline of designing the contract before writing the implementation. It sounds like a small change in order. It's actually a significant change in how teams work, how fast they can move in parallel, and how much rework they avoid.

What API-First actually means

API-First means: the API contract is the first deliverable, not a byproduct of the implementation.

Before any backend code is written, the team agrees on:

• What endpoints exist
• What the request shapes look like
• What the response shapes look like
• What the error cases are
• What authentication the API requires

That contract is written down — usually as an OpenAPI spec, a GraphQL schema, or a similar machine-readable format. Once it's agreed, frontend and backend can work in parallel: the frontend builds against a mock server generated from the spec, the backend implements against the spec, and integration is a matter of swapping the mock for the real thing.

That's the workflow. The question is why it's worth the discipline.

Why the order matters

Parallel development. The most immediate benefit. If the frontend team is waiting for the backend to be "done enough" to integrate against, you've serialised work that could be parallel. An agreed spec with a mock server breaks that dependency. Both teams can move at full speed from day one.

Design pressure before implementation pressure. When you design the API before writing the implementation, you're thinking about the consumer's experience — what's easy to call, what's easy to understand, what's easy to handle errors from. When you design the API after writing the implementation, you're thinking about what's easy to expose from the code you've already written. Those are different pressures, and the first one produces better APIs.

Fewer breaking changes. APIs that are designed with consumers in mind from the start tend to be more stable. The breaking changes that cost the most — renaming fields, changing response shapes, restructuring error formats — usually happen because the API was designed for the implementation, not the consumer. Getting the consumer's perspective in before the implementation is written catches those problems cheaply.

Documentation that's always current. If the spec is the source of truth and the implementation is generated from or validated against it, the documentation is always current. If the documentation is written after the implementation, it's always slightly wrong.

The practical workflow

Step 1: Draft the spec. Write the OpenAPI spec (or GraphQL schema) for the feature. This doesn't need to be perfect — it needs to be good enough to unblock parallel work. A first draft takes an hour for a typical feature.

Step 2: Review the spec with consumers. The frontend team, the mobile team, any external integrators — whoever will call the API reviews the spec before implementation starts. This is where you catch the "actually, we need the user's name in the order response" problems before they're implementation problems.

Step 3: Generate a mock server. Tools like Prism (for OpenAPI) or MSW (for frontend mocking) can generate a mock server from the spec in minutes. The frontend team builds against the mock. The backend team implements against the spec.

Step 4: Implement against the spec. The backend implementation is validated against the spec — either through generated types, contract tests, or both. If the implementation drifts from the spec, the build fails.

Step 5: Swap mock for real. When the backend is ready, the frontend swaps the mock server URL for the real one. Integration is usually a non-event because both sides were building against the same contract.

What to use for the spec

OpenAPI (formerly Swagger) is the standard for REST APIs. It's verbose but tooling support is excellent — mock servers, client generation, documentation, contract testing, all from the same spec file. For a new REST API, this is the default choice.

GraphQL schema is the spec for GraphQL APIs. The schema is the contract; the implementation is validated against it by the runtime. If you're building a GraphQL API, the schema-first approach is the natural expression of API-First.

tRPC (for TypeScript full-stack) takes a different approach — the types are the contract, shared between client and server. It's not API-First in the traditional sense, but it achieves the same goal: the contract is defined once and both sides are validated against it.

AsyncAPI for event-driven APIs — message queues, webhooks, event streams. Less common but worth knowing if you're designing an event-driven system.

The mistakes that make API-First painful

Treating the spec as documentation, not a contract. If the spec is written after the implementation and updated manually, it will drift. The spec needs to be the source of truth — either the implementation is generated from it, or the implementation is validated against it. One of those two, not neither.

Designing the spec in isolation. The spec should be reviewed by the people who will call the API before implementation starts. A spec designed by the backend team without input from the frontend team will be optimised for the backend, not the consumer.

Over-specifying too early. The first draft of the spec doesn't need to cover every edge case. It needs to cover enough to unblock parallel work. Over-specifying early creates a false sense of completeness and makes the spec harder to change when you learn something new.

Skipping versioning. If the API will have external consumers — mobile apps, third-party integrators, partner systems — versioning needs to be in the spec from day one. Adding it later is painful. The simplest approach: version in the URL (/v1/, /v2/) and commit to not making breaking changes within a version.

When API-First is most valuable

API-First pays off most when:

• Multiple consumers. Web frontend, mobile app, third-party integrators — each with different needs. The spec is the single source of truth that all of them build against.
• Parallel teams. Frontend and backend working simultaneously. The spec breaks the dependency.
• External APIs. APIs that will be called by partners or customers. The spec is the contract you're committing to; getting it right before implementation is worth the investment.
• Long-lived products. APIs that will need to evolve over years. The discipline of spec-first makes versioning and evolution more manageable.

API-First is less critical for:

• Internal APIs with a single consumer. If the frontend and backend are owned by the same person and the API is never exposed externally, the overhead of a formal spec may not be worth it. The ideas still apply; the ceremony may not.
• Rapid prototyping. When you're exploring whether something is possible, not committing to a contract. Build the prototype, then apply API-First when you're building the real thing.

TL;DR

Design the contract before writing the implementation. Write it down in a machine-readable format. Review it with consumers before implementation starts. Generate a mock server from it. Validate the implementation against it.

The order matters because design pressure before implementation pressure produces better APIs. Parallel development from a shared spec produces faster teams. A spec that's the source of truth produces documentation that's always current.

The discipline is small. The payoff — in parallel velocity, in fewer breaking changes, in better consumer experience — is large.

If you're designing an API for a new product or rethinking an existing one, let's talk.