Aroma Store's v1 contract is complete: resources, URIs, methods, codes, representations, collections and a versioning policy. But a contract that only exists in the heads of the team that designed it is not a contract: it is a tacit agreement waiting to be broken. This lesson covers the piece that turns the design into something other people can use. We will see why documentation is part of the product and not an extra, which kinds of document serve which reader, what each endpoint's reference must include, and what changes radically when the contract is written in a machine-readable format such as OpenAPI. We close module 2 by taking stock of the whole designed contract and preparing for the jump to module 3.

1. Documentation is part of the product
2. Types of documentation and who each one serves
3. Anatomy of an endpoint's reference
4. Contract-driven documentation: OpenAPI
5. A real fragment: GET /coffees in OpenAPI
6. What a machine-readable specification unlocks
7. Documentation as code
8. Good writing practices
9. Keeping documentation alive
10. Taking stock of Aroma Store's contract

An API has no visual interface. There are no buttons to explore and no menus hinting at what you can do. For a developer consuming it, the documentation literally is the product: if it is not documented, it does not exist.

Think about it from the other side. When SwiftShip's team sits down to integrate with Aroma Store, their experience consists of: reading, trying a curl, reading again, writing code, hitting an undocumented error, writing an email, waiting two days. Every one of those steps is cost. What good documentation reduces is not "annoyance": it is time to the first correct call, the metric that decides whether your API gets adopted or abandoned.

Practical consequences of taking it seriously:

• It is planned and estimated like any other feature. An undocumented endpoint is not finished.
• It is tested: the examples are run, not copied from memory.
• It has an owner and it is reviewed in pull requests.
• It reduces support: every question that arrives by email is a question the documentation failed to answer, and the right response is not to answer the email but to fix the documentation.

The most common mistake is writing a single giant document. There are different readers, at different moments, with incompatible needs.

The goal is one single thing: one correct call in under five minutes. No architecture, no theory.

curl -H "Authorization: Bearer YOUR_TOKEN"
"https://api.aromastore.example/v1/coffees?limit=3"

{ "data": [ { "id": "cof_001", "name": "Ethiopia Yirgacheffe", "priceEuros": 14.50 } ], "total": 137 }

It explains the mental model, which no reference conveys. For Aroma Store: what a cart is and how it differs from an order, the order state machine, the review moderation cycle, how signed webhooks work, what it means for identifiers to be opaque. Without this, the integrator infers the model by trial and error, and infers it wrongly.

They walk through a complete use case from start to finish: "From cart to paid order", with the seven chained calls, their real responses and the likely errors at each step. It is what people are most grateful for and what gets written least.

One entry per change, with the date, the type (added / changed / deprecated / removed / fixed) and a link to the migration guide where relevant:

It is the cheapest document to maintain and the one that builds the most trust: it shows that the API is alive and that changes are announced.

The reference is what gets consulted daily. Every endpoint needs all of these elements; if one is missing, somebody will end up asking about it by email.

An abbreviated example of how it looks for Aroma Store:

curl -i -X POST "https://api.aromastore.example/v1/orders/ord_5001/payment"
-H "Authorization: Bearer $AROMA_TOKEN"
-H "Idempotency-Key: 5f3b9c2a-1d7e-4a44-9f30-8b1c2d3e4f50"
-H "Content-Type: application/json"
-d '{ "method": "card", "cardToken": "tok_visa_4242" }'

The error column is the one most often left out and the one that prevents the most incidents: without it, the integrator discovers the 409 the day a user clicks twice.

Everything above can be written by hand in Markdown. It works, and for a small API it may be enough. But there is an alternative that changes the rules of the game: writing the contract in a format machines understand.

OpenAPI (formerly Swagger) is a specification —today at version 3.1— for describing an HTTP API in YAML or JSON: its paths, methods, parameters, data schemas, responses, errors and security. It is not documentation about the API: it is the API described formally, and readable documentation is only one of its outputs.

The difference from hand-written documentation is one of nature, not of degree: a Markdown document describes the contract and can lie; an OpenAPI specification is the contract and can be verified against the implementation automatically.

This lesson stops at the why and at an illustrative fragment. Swagger and OpenAPI in depth —editors, generators, the interactive interface, good writing practices— are lesson 05-02, and using the contract for mocks and automated tests is 05-04.

This is what the contract of the coffee collection we designed in 02-06 looks like, written in OpenAPI 3.1:

Notice how much of this module's contract is encoded here, and verifiably so:

• The default limit of 20 and maximum of 100, and the offset cap (02-06).
• The id tie-break in the ordering, documented in the description.
• The data/total envelope (02-05) and the error format with code/message/details (02-04).
• The identifier's pattern and the opacity warning (02-02).
• Amounts with multipleOf: 0.01, that is, two decimals (02-05).
• The warning that the roast enumeration may grow (02-07).
• The Link header as a declared part of the response.

The $refs to components avoid repeating limit, offset, Coffee and Error on every endpoint: they are written once and referenced, which is exactly the consistency 02-01 asked for, now guaranteed by construction.

The most important one for an API-first project like ours is the mock: with the openapi.yaml finished, the SPA and Aroma Mobile can start integrating on day one against a simulated server while the server team implements. That is what makes "design before you program" not lost time but parallelism gained.

Documentation is treated exactly like code:

• It lives in the repository, next to the implementation. openapi.yaml at the root, guides in docs/.
• It is versioned with Git, so the history answers "since when has it said this?".
• It is reviewed in pull requests: an API change that touches neither the contract nor the changelog is not approved.
• It is validated in continuous integration: the specification is checked syntactically, a style linter is run and the contract tests are executed.
• It is published automatically when merged into the main branch.

Typical structure of the Aroma Store repository:

The detail that makes this genuinely work: the quality gate in CI. If the pipeline fails when the implementation does not comply with the contract, documentation stops depending on goodwill. It is set up in 05-05.

Real, copyable examples. No <YOUR_ID_HERE> mixed in with fake data. Use the domain's identifiers (cof_001, ord_5001, cus_842) consistently across the whole documentation: whoever reads a tutorial recognises the same data in the reference.

A complete curl, always. With the authentication header, the URL in quotes (because of the &, as we saw in 01-03) and the whole body. It is the lowest common denominator: it works on any system and it assumes no programming language.

Document the errors as much as the successes. It is the most visible difference between professional and amateur documentation.

Explain the why, not just the what. "Idempotency-Key is mandatory because a retry after a timeout could charge twice" teaches; "Idempotency-Key: string, required" merely informs.

No "TBD", "to be documented" or "pending". A declared gap is worse than an absence: the reader wastes time trusting that it will turn up.

Consistency with the style guide. If the guide says camelCase, no example carries snake_case. Documentation is where inconsistencies show, and where they destroy trust fastest.

Write for someone who does not know your domain. The first use of "cart", "item" or "moderation" deserves a definition. SwiftShip's team knows about logistics, not about speciality coffee.

Careful with screenshots. They age badly and they cannot be searched or copied. Prefer code blocks.

The enemy has a name: drift, the gap that opens between what the documentation says and what the API does. A badly documented API is a problem; an API that is badly documented but looks well documented is worse, because the integrator trusts it and fails.

Aroma Store uses the mixed approach: a hand-written openapi.yaml —it is the source of truth, consistent with the API-first stance of 02-01— and contract tests in CI that fail if the implementation deviates. Guides and tutorials are always written by hand: no generator explains why a cart is not an order.

• The changelog has had no entries for months, but the API has changed.
• The examples use fields that no longer exist.
• There are endpoints in production that do not appear in the specification.
• The real error responses do not match the documented ones.
• The team answers questions over chat that the documentation should be answering.

This is what we have designed over the course of module 2, and it is exactly what module 3 is going to implement.

Method and principles (02-01). An API-first approach, identified consumers (SPA, Aroma Mobile, internal panel, SwiftShip), resources extracted from the domain and a written style guide.

Resources and URIs (02-02). A complete map of 24 URIs on https://api.aromastore.example/v1, lowercase plurals, kebab-case, a maximum of two levels of nesting, singular singletons, opaque prefixed identifiers and non-CRUD actions modelled as sub-resources with POST (/payment, /cancellation, /approval, /rejection).

Methods (02-03). GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS assigned resource by resource; PATCH with JSON Merge Patch; soft deletes invisible from the outside; Idempotency-Key mandatory on POST /orders and POST /orders/{id}/payment.

Codes (02-04). The codes that actually get used, with 201 + Location, 409 for state conflicts, the 401/403 and 404/410 distinctions; an in-house error format {"error": {"code", "message", "details"}} against problem+json; a catalogue of 28 business error codes.

Representations (02-05). camelCase, ISO-8601 UTC, euros with two decimals, extensible snake_case enumerations, null versus absent, the data/total envelope, the criteria for embedding versus linking, _links for selective hypermedia, expand and fields, and negotiation with Accept, Accept-Language, Accept-Encoding and Vary.

Collections (02-06). Explicit filters, Min/Max and From/To ranges, multi-value with commas, sort with an id tie-break, offset for /coffees and cursors for /orders, total in the body and navigation in the Link header, ?q= for search, and default and maximum limits.

Evolution (02-07). The version in the path, two live versions at most, 12 months of deprecation, Deprecation and Sunset headers and shutdown with 410 Gone.

Documentation (02-08). openapi.yaml as the source of truth, hand-written guides and tutorials, a changelog by date, everything in the repository and validated in CI.

• Leaving documentation until the end. That end never arrives. Document the endpoint in the same pull request that creates it.
• Documenting only the happy path. Errors are half the integrator's work: undocumented 409s and 422s generate incidents nobody can explain.
• Examples that cannot be run. Test every curl in the documentation. If one example fails, you have lost the reader's trust in everything else.
• Confusing the reference with a guide. The reference says what an endpoint accepts; it never explains how to chain six calls to pay for an order. You need both.
• Generating documentation from the code and calling it good. It documents what exists, bugs included, and it says nothing about concepts or intent.
• Not documenting the limits. Rate limits, maximum sizes, the maximum limit and expansion depth are part of the contract: without them, the integrator discovers them with a 400 in production.
• Forgetting the changelog. It is the cheapest document and the one an external consumer appreciates most.
• Tip: measure the "time to the first correct call". Sit down with somebody who does not know the API, give them the documentation and time them in silence. You will learn more in twenty minutes than in three meetings.
• Tip: treat every support question as a documentation failure. The answer is not to reply to the email, it is to fix the document and then reply with the link.

Write the complete reference documentation for POST /v1/coffees/{coffeeId}/reviews with all the elements from section 3. Use the contract designed in this module: the body carries rating (an integer from 1 to 5) and comment (text of up to 5,000 characters); the review is created with the status pending_moderation; only customers who have bought that coffee can review it.

Extend the fragment from section 5 by adding the GET /coffees/{coffeeId} operation: the path parameter, a 200 response with the reused Coffee schema, a 404 response with the Error schema and an example of the coffee_not_found error, and a 304 response for conditional caching. Reuse the existing components.

A developer joins Aroma Store and finds this. Identify all the documentation problems and propose the concrete remedy and the process that would stop it happening again.

• The reference says GET /v1/coffees returns an array; the API returns {"data": [...], "total": n}.
• There is no mention at all of the expand parameter, which nevertheless works.
• The POST /v1/orders example does not include the Idempotency-Key header, which is mandatory.
• The error table for POST /v1/orders/{id}/payment only lists 400 and 500.
• The changelog stops eight months ago.
• There is a /v1/promotions endpoint in production that appears nowhere.

Solution 1

curl -i -X POST "https://api.aromastore.example/v1/coffees/cof_001/reviews"
-H "Authorization: Bearer $AROMA_TOKEN"
-H "Content-Type: application/json"
-d '{ "rating": 5, "comment": "Citrus and floral, spectacular in a V60." }'

HTTP/1.1 201 Created Location: https://api.aromastore.example/v1/reviews/rev_101

{ "id": "rev_101", "coffeeId": "cof_001", "customerId": "cus_842", "rating": 5, "comment": "Citrus and floral, spectacular in a V60.", "status": "pending_moderation", "createdAt": "2026-03-14T10:30:00Z", "_links": { "self": { "href": "/v1/reviews/rev_101" }, "coffee": { "href": "/v1/coffees/cof_001" } } }

Notice that a new error code has appeared, duplicate_review (409): documenting forces you to close decisions the design had left open. That is one of the great benefits of writing the reference before implementing.

Solution 2

Note that Coffee and Error are reused with $ref: when a field is added to the Coffee schema tomorrow, it automatically appears in both operations and in the generated documentation. That is consistency guaranteed by construction, not by human review.

Solution 3

The process that prevents all of it, in one sentence: the specification is the source of truth, it lives in the repository, it is validated on every pull request and the pipeline fails if the implementation does not comply with it. Without an automatic gate, drift is only a matter of time.

Documentation is not what you write after programming: it is the visible face of a product that has no interface. You now know that different readers need different documents —quick start, concepts, tutorials, reference, changelog—, what each endpoint's reference must contain (including all of its errors, which is what gets left out most), and why writing the contract in OpenAPI changes the nature of the matter: it stops being a text that describes the API and becomes the contract itself, out of which come the browsable documentation, the clients, the mocks, the tests and the gateway configuration. With documentation as code, reviewed in pull requests and validated in CI, drift stops depending on goodwill.

With this we close module 2. You have designed, piece by piece and on paper, the complete contract of the Aroma Store API: its working method and its style guide, its 24 URIs with the actions modelled as sub-resources, its methods with the idempotency of payment resolved, its table of codes and its catalogue of business errors, its representations with selective hypermedia, its filtered and paginated collections, its versioning and deprecation policy, and its documentation. None of this has needed a single line of server code yet, and that was exactly the idea: in API-first, the contract goes first. Now it has to be honoured. In module 3, Developing RESTful APIs, we will set up the environment with Node.js 20, bring up the server with Express and turn every decision from this module into code: the routes of the URI map, the validation that returns invalid_data with its details, the persistence layer that converts cents into euros, the authentication that distinguishes 401 from 403, the error middleware that emits the format we have fixed and the tests that verify the implementation respects the contract. We start at the beginning: 03-01, Setting Up the Development Environment.