Writing the contract down
🎯You'll be able to
Describe an API in an OpenAPI document, keep it in step with the code, and use it to review changes before they ship.
🏠The everyday picture
A rental agreement lists exactly what the tenant and owner each promise. Nobody has to remember a conversation from two years ago; they read the document.
📘What it really is
-
OpenAPI (version 3.1) is a standard file (YAML or JSON) that lists each path, method, parameter, request body, response and error, with their types.
-
From one OpenAPI file you can produce documentation pages, client code, mock servers, and request validation.
- Two ways to work:
- design-first: agree the OpenAPI file in review, then write code to match;
-
code-first: generate the file from the code's annotations. Either works if the file and the code are checked against each other automatically (Module 49, and contract tests in BE9).
-
Document the unhappy paths: every 4xx response, the error format, rate limits, and which permission each route needs.
- Review an API change by diffing the OpenAPI files: a removed field or a new required parameter is easy to spot.
📝A worked example
Part of an OpenAPI description for placing an order:
/v1/orders:
post:
security: [{ bearer: [orders:write] }]
parameters:
- { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 8, maxLength: 64 } }
requestBody:
content: { application/json: { schema: { $ref: '#/components/schemas/NewOrder' } } }
responses:
'201': { description: Order placed, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
'200': { description: Repeat of an earlier request with the same key; the first order is returned }
'400': { $ref: '#/components/responses/Problem' }
'401': { $ref: '#/components/responses/Problem' }
'403': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/TooManyRequests' }
Expected outcome: a developer at a partner company can build a correct client, including retries and error handling, from this file alone.
🌍Where it's used
- Partner and public APIs, where the document is the product.
- Large teams, where frontend and backend agree the contract before building.
- API gateways (BE8), which can load OpenAPI files to route and validate requests.
📝Case scenario
A team's documentation page says quantity, but the code reads qty, because the page was written by hand a year ago. A partner
spends two days on a "bug" that is really out-of-date documentation. Adding a test that validates real responses against the OpenAPI
file would have caught it on the day the code changed.
🖱️Try it
Write an OpenAPI description of GET /v1/kitchens/{id}/menu and POST /v1/orders, including every error response. Paste it into
an OpenAPI viewer (several free ones run in the browser). Success: every status code the kit's tests expect appears in your file.
⚠️Common mistakes
- Documenting only success. Sign: no 4xx responses in the file. Fix: describe every error, with the shared error format.
- Hand-written docs that drift. Sign: field names in the docs don't match the API. Fix: check the file against real responses in tests.
- Leaving out permissions. Sign: callers find out about scopes from 403s. Fix: list the required scope on each operation.
🛠️For your project
Your Project 1 evidence includes an OpenAPI file for the three order and menu routes, matching what the tests check.
✅Quick check
What can you generate from one OpenAPI file?
Show the answer
Documentation, client code, mock servers and request validation.
How do you stop documentation drifting from the code?
Show the answer
Check real requests and responses against the OpenAPI file automatically, for example in tests.