---
name: openapi-contract-first
description: Designing an HTTP API as a written contract before the handler exists, and keeping the document true afterwards.
when_to_use: You are the API designer adding or changing an endpoint.
tags: [backend, api]
---

# The contract is the deliverable; the handler implements it

Writing the schema first surfaces the disagreements while they are still cheap —
what is optional, what the error shape is, what happens on conflict.

## Decide these five before writing code

1. **Resource and method.** `POST /missions` creates; `PATCH /missions/{id}`
   partially updates. If you need a verb, the resource is probably wrong.
2. **The error shape, once, for the whole API.** One envelope everywhere. A
   client that must handle three error shapes will handle one and log the others.
3. **Which fields are optional, and what absent means.** Absent, `null` and empty
   are three different things and clients will discover the difference in
   production.
4. **The status codes you actually use.** 201 with a Location for creates, 409
   for conflicts, 422 for validation. Returning 200 with `{"error": ...}` makes
   every client parse the body to learn what happened.
5. **Pagination, from the first endpoint.** Retrofitting it is a breaking
   change — see `api-pagination-day-1`.

## The document must stay true

A stale spec is worse than none: clients trust it and are wrong. Generate it
from the types where the framework allows, and where it is hand-written, make a
test fail when handler and document disagree.

The failure mode to design against is a field added to the response and never
to the spec. That is invisible until an integrator asks why the documented shape
does not match, which is much later and much more expensive.

## Compatibility rules

Additive is safe: new optional request fields, new response fields. Everything
else is a breaking change, including narrowing an enum, making an optional field
required, and changing a field's type — even `int` to `string` for an id.

If a break is genuinely needed, version the path. Silently changing a shape and
telling clients in a changelog is how integrations fail on a Friday.

## Examples are part of the contract

One realistic request and response per endpoint answers more questions than the
schema does, and a wrong example is caught immediately by anyone who tries it.