API contracts before code: agree on the interface first

In many projects the API is the last thing to take shape: the server builds one thing, the interface expects another, and in the final week it turns out they don't fit. A contract-first approach reverses that order.

What an API contract is

An API contract is a precise description of how two parts of a system talk: which requests exist, what input each takes, what output it returns and what happens on failure.

It is written and approved before any code, on paper or in a standard API description format.

Why contract first

Parallel work

With the contract fixed, the interface team works against sample data while the server team implements the same contract. Neither waits for the other.

Disagreements surface early

Most misunderstandings appear while the contract is being designed: "Is this field required?", "What comes back when stock is zero?" Answering those on paper takes minutes; in code it takes days.

Integration without surprises

Joining the parts — usually the most tense phase of a project — becomes a simple check: did both sides honour the contract?

Documentation for free

A contract written up front is the documentation, and it doesn't go stale because it was the basis of the work.

Rules for a good contract

Speak the product's language, not the database's. An API should not mirror the tables. A user "places an order", not "inserts rows into three tables".

Name things consistently. If you wrote createdAt in one place, don't write creation_date in another. Small inconsistencies cause large bugs.

Errors are part of the contract. Every request defines its failures as well as its success, with machine-readable codes:

{ "ok": false, "code": "RATE_LIMIT", "retryAfter": 60 }

Paginate from the start. A list with ten items today will have ten thousand next year.

Expose only what is needed. Every field you publish is a field you have promised to maintain. Removing is always harder than adding.

Validate at the boundary. Input is checked where it enters, and the rules are stated in the contract.

Versioning and change

Contracts don't stay fixed, but change needs rules:

• Adding a field or endpoint is usually safe.
• Removing or changing meaning is always breaking and needs a new version and a transition period.
• Every change is recorded in the contract first, then in code.

Contracts for non-human consumers

The consumer of an API is no longer only a user interface. AI agents call their tools through the same contracts. For them clarity matters even more: a precise description of each action, well-defined inputs and understandable errors directly affect the quality of the agent's decisions.

Where it sits in the process

In my process, the API contract is an output of the architecture stage, alongside the system map, the data model and the decision records. Until those are approved, the build doesn't start.

The contract is also the basis of swappable layers: when the interface is stable, what sits behind it can change.

Common mistakes

• Writing the contract after the code. Then it only describes what was built; it isn't an agreement.
• Designing alone. Consumer and producer should design the contract together.
• Ignoring errors. The happy path is half the contract.
• A contract without examples. One real request and response is clearer than ten paragraphs.

The takeaway

A few hours agreeing on the contract removes weeks of back-and-forth at integration. Interface first, implementation second.

For architecture and contract design, see architecture and technical planning.