We closed module 1 by saying it was time to move from understanding to building. Before writing the first line of server code there is a stage that far too many people skip, and it is exactly where API projects are won or lost: designing the contract. This is the umbrella lesson of module 2. It does not yet cover how URIs are named or which status code to return —those are the lessons that follow— but rather the working method: how you decide which API needs building, with which guiding principles and with which artefacts. By the end of the lesson you will be holding the Aroma Store API style guide, a living document that the next seven lessons will fill in and that module 3 will implement to the letter.

1. API-first versus code-first
2. The design process in seven steps
3. Step 1: identify consumers and use cases
4. Step 2: extract the nouns of the domain
5. Step 3: decide what becomes a resource and what does not
6. Guiding design principles
7. Granularity: neither too fine nor too coarse
8. Design for the consumer, not for the database
9. Tolerance to change and the robustness principle
10. The Aroma Store API style guide
11. Map of module 2

There are two ways of ending up with an API, and they do not produce the same result.

In the code-first approach you write the application first and the API appears afterwards, almost as a by-product: you take the services that already exist, hang an HTTP layer off them and generate the documentation from the code. It is fast at the start and works reasonably well when the only consumer is your own frontend.

In the API-first approach you do the opposite: the contract is designed, reviewed and agreed before anything is implemented. The specification is the primary artefact; the code is its realisation. Consumers can start working against a mock generated from the contract while the server team implements it.

Aroma Store has four different consumers and one of them is an external company. Redesigning the contract after SwiftShip has integrated its systems costs meetings, versions and money. That is why this course adopts API-first: the whole of module 2 designs the contract on paper and module 3 implements it.

An honest caveat: API-first does not mean "design everything perfectly before touching code". It means that the contract goes first and gets reviewed the way code gets reviewed. You can iterate, but you iterate on the document, not on an API that is already published.

Steps 1 to 3 are this lesson. Steps 4 and 5 are lessons 02-02 to 02-06. Step 6 lands in 02-07 and 02-08. Step 7 is worked through in depth in 05-04. The cycle closes: what you learn validating with consumers goes back to the beginning.

An API is not designed "for the domain": it is designed for someone who is going to call it. The first deliverable is not a list of endpoints but a list of consumers with their real needs.

Out of that come the use cases, written as user sentences rather than endpoints:

• "As a visitor I want to see the available coffees filtered by origin and roast."
• "As a customer I want to add two bags of Ethiopia Yirgacheffe to my cart and pay for it."
• "As a customer I want to check the status of my order and download the invoice."
• "As a moderator I want to approve or reject a pending review."
• "As SwiftShip I want to find out that an order has been paid without having to ask every minute."

That last use case is the one that made webhooks appear in 01-07: the list of use cases also decides the architecture, not just the endpoints.

One important detail: consumers have different and sometimes conflicting needs. Aroma Mobile wants small responses because it pays for the network; the internal panel wants rich responses because it paints tables with many columns. That tension is not resolved by creating two parallel APIs but with contract mechanisms: sparse fieldsets and expansion, designed in 02-05.

The technique is deliberately simple: write in prose what the business does and underline the nouns.

"A customer browses the catalogue of coffees, each one with its origin, its roast and its tasting notes. They add items to their cart and confirm an order, which has a total and a status. The order is paid and generates an invoice. When it is paid, SwiftShip creates a shipment. Afterwards, the customer can write a review of a coffee, which a moderator approves or rejects, and to which the shop can publish a reply."

Candidate nouns: customer, catalogue, coffee, origin, roast, tasting notes, item, cart, order, total, status, payment, invoice, shipment, review, reply, moderator.

And the verbs, which we note down separately because they are the source of the most interesting problems: browse, add, confirm, pay, generate, approve, reject, reply.

Not every noun deserves a URI. Apply these filters:

1. Does it have its own identity? Can you point at it and say "that one there"? An order does (ord_5001); a total does not: it is an attribute of an order.
2. Does anyone need to address it separately? A review does: it is moderated one at a time. A roast does not: it is a value of an enumeration.
3. Does it have its own lifecycle? A shipment is born, changes state and ends. A tasting note does not: it lives and dies with its coffee.
4. Is it manipulated independently of its parent? A cart item is, because you change its quantity without touching the rest.

Applied to Aroma Store:

The right-hand column is justified in 02-02, which is where naming rules, nesting and singletons are explained. What matters here is the criterion: a resource is something that has identity, a lifecycle and a need to be addressed.

These six principles are the ones we will apply, lesson after lesson, every time something has to be decided.

If /coffees accepts ?limit=20, then /orders accepts ?limit=20, even if for orders you would have preferred to call it ?size. An API with twenty good but mutually different decisions is worse than an API with twenty acceptable and identical ones: the consumer learns the first and infers the other nineteen.

A developer who has already used GET /v1/coffees/cof_001 should be able to write GET /v1/orders/ord_5001 without opening the documentation and get it right. A practical test: show someone three endpoints and ask them to write the fourth. If they get it right, the API is predictable.

The API exposes things you operate on with the HTTP methods, not remote functions. POST /v1/orders/ord_5001/payment instead of POST /v1/payOrder. We already justified this in 01-04 and 01-05; the hard case —actions that do not fit into CRUD— is solved in 02-02.

If the GET of a coffee returns priceEuros and stock, the POST that creates it should accept those same field names. If POST /coffees returns the created resource, PUT /coffees/{id} should also return the updated resource. Gratuitous asymmetries force people to memorise exceptions.

Everything the consumer can observe is part of the contract: field names, types, status codes, headers, error messages, a collection's default ordering. Whatever you do not want to guarantee, do not expose. And whatever you do expose, do not change without versioning (02-07).

An error is just another response and is designed just as carefully as a success. It must say what failed, why and what the client can do about it. The format is fixed in 02-04.

Granularity is how much work a single call does. It is one of the decisions with the widest consequences and it has no universal answer.

An API that is too fine. Every minimal resource has its endpoint and the client composes. Painting a coffee's detail page forces you to: fetch the coffee, fetch its reviews, fetch the customer of each review... This is chattiness: lots of round trips. On a mobile network with 150 ms of latency, eight chained calls are more than a second lost purely in travel.

An API that is too coarse. A single endpoint returns the coffee with its reviews, the customers who wrote them, the stock per warehouse and the recommendations. One single call, but: enormous responses, almost all of it unused (over-fetching), useless caching (any change invalidates everything) and a contract coupled to one particular screen that will break when the screen changes.

Aroma Store's stance: a medium-granularity, resource-oriented API, with two controlled escape valves designed in 02-05 —expansion (expand) to reduce calls and sparse fieldsets (fields) to reduce weight— plus data already embedded where real usage demands it (the coffee's name inside an order item, so that the client does not have to resolve every coffeeId).

The most frequent and most expensive mistake: publishing your tables. You take the relational schema, generate one endpoint per table and call that a REST API.

Here is what happens when we expose the coffees table as it stands:

Problems: the consumer has to translate roast_code: 1 into "light" using a table they do not have; origin_fk: 12 tells them nothing; price_cents forces them to know a storage decision; soft_deleted, created_by and row_version are internal plumbing that is now part of the contract and cannot be removed without breaking clients. And if the table gets normalised tomorrow, the API breaks.

The representation designed for the consumer:

The rule is: the representation is a projection designed for whoever reads it, not a dump of the row. The database can carry on storing cents, foreign keys and deletion flags; that is the persistence layer's business (03-05).

Jon Postel's robustness principle says: "be conservative in what you send, liberal in what you accept". Translated into an API:

• As a server: emit exactly what the contract promises. No fields that appear only sometimes and no types that change.
• As a client: do not break because a field you were not expecting turns up. This is the tolerant reader, and it is what allows the server to add fields without publishing a new version.

Design consequences we adopt right away:

• Enumerations can grow. If roast: "very_dark" shows up tomorrow, clients must ignore it gracefully rather than blow up. This is documented from day one.
• New fields are optional and additive.
• A field name is never reused with a different meaning.
• Collections are wrapped in an object ({"data": [...], "total": n}) precisely so that metadata can be added without changing the type of the response. The argument is made in 02-05.

Exactly what counts as a breaking change and what does not, and how deprecation is managed, is lesson 02-07.

This is the central artefact of the module. A style guide is a short document, versioned in the repository, where the conventions that the whole API respects are written down. It serves three purposes: deciding quickly, reviewing in pull requests and onboarding new people.

We start with the decisions already taken (module 1) and the ones this module will close out:

Two warnings about style guides:

1. They are written to be complied with. A guide nobody checks in pull requests is decoration. In 05-05 we will see how to automate part of the checking (OpenAPI linters).
2. Conventions are arbitrary, consistency is not. camelCase is not objectively better than snake_case; what is objectively worse is using both.

By the end of the module you will have the complete contract of the Aroma Store API: its URIs, its methods, its codes, its representations, its paginated collections, its versioning policy and its documentation. Module 3 implements it with Node.js and Express without inventing anything new.

• Starting with the endpoints. If your first design sheet is a list of URLs, you have skipped the consumers and the domain. Start with use cases written in business language.
• Designing the API while looking at the ORM. Column names, foreign keys and internal flags are not contract. Project, do not dump.
• Designing the API while looking at the screen. The opposite extreme and equally damaging: endpoints that only serve one particular view age with that view. Design resources and give the client tools (fields, expand) to adapt them.
• Optimising before you have the problem. Do not add expansion, exotic filters or business caching "just in case". Every mechanism in the contract has to be documented, tested and maintained forever.
• Confusing consistency with rigidity. There will be legitimate exceptions (the PDF invoice, for example). What matters is that they are few, deliberate and written down in the style guide, not accidents.
• Tip: write the response first. Before deciding the URL, write out by hand the JSON you would like to receive in the main use case. Many design decisions clear themselves up as soon as you see it.
• Tip: the new developer test. If someone who did not take part in the design needs to ask what the pagination parameter is called, the API is not predictable yet.

Aroma Store wants to add subscriptions: a customer receives a bag of coffee every month, with a frequency, a payment method, a delivery address and a history of deliveries already made. On top of that, each subscription can be paused.

Decide, justifying it with the four criteria in section 5, which of these nouns are resources and which are attributes: subscription, frequency, payment method, delivery address, delivery, pause.

The "my orders" screen in Aroma Mobile currently makes these calls:

And the screen only shows, per order: date, status, total and the name of the first coffee. Diagnose the problem and propose two different design solutions, stating the drawback of each one.

Add three new rows to the table in section 10 that are not there today and that you know will be needed, covering these three matters: (a) what Aroma Store's own headers are called, (b) which time zone is used in the input dates the client sends, (c) what happens to unknown fields that a client sends in the body of a POST. Write the convention in one sentence per row.

Solution 1

Solution 2

Diagnosis: an API that is too fine for this use case. The screen needs four pieces of data per order and triggers something like 38 calls. That is pure chattiness, made worse by the fact that Aroma Mobile suffers mobile network latency. There is also over-fetching in the other direction: for each coffee everything gets downloaded just to read name.

Solution A — have the collection return what gets painted. GET /v1/customers/cus_842/orders returns each order with createdAt, status, totalEuros and the items with the coffee's name already embedded. A single call. Drawback: the coffee's name is duplicated across many responses and that copy has to be kept consistent; on top of that the response grows for every consumer, including those that do not need the items.

Solution B — expansion and sparse fieldsets. GET /v1/customers/cus_842/orders?expand=items.coffee&fields=id,createdAt,status,totalEuros,items. One call, and each consumer asks for what it needs. Drawback: mechanisms that have to be documented, validated and tested; they open the door to expensive queries and complicate caching, because every combination of parameters is a different URL.

(Aroma Store's decision combines the two: it embeds the coffee's name in the items —stable data that is always needed— and offers expand/fields as an escape valve. This is settled in 02-05.)

Solution 3

About the last one: it is a debatable decision and worth understanding. Rejecting unknown fields (strict) catches client typos instantly; ignoring them (tolerant) makes it easier for a new client to talk to an old server. Aroma Store is strict on input and tolerant on output, which is exactly the robustness principle from section 9.

Designing a RESTful API does not start by drawing URLs: it starts by knowing who is going to use it and what for, extracting the nouns of the domain and deciding with judgement which of them deserve to be resources. From there, a handful of guiding principles —consistency, predictability, resource orientation, symmetry, a stable contract and useful errors— resolve most day-to-day decisions, while granularity and the refusal to expose the database avoid the two most expensive structural mistakes. All of that materialises in one concrete artefact: the style guide, which we have opened with Aroma Store's already firm decisions and which we will fill in lesson by lesson.

With the method clear and the consumers identified, it is time for the first concrete decision of the contract: which resources exist and what their URIs are called. In the next lesson, 02-02 Resources and URIs, we will turn the list of nouns into a complete map of addresses —collections, elements, nested sub-resources and singletons—, we will fix the naming rules, distinguish what goes in the path from what goes in the query string, choose the type of identifier and solve the problem that no CRUD solves on its own: how to model actions such as paying for an order or moderating a review.