The envelope is already designed: we know which URI the request goes to, with which method and with which code the server responds. What is missing is what goes inside. This lesson designs the body of Aroma Store's responses —field names, their types, how dates and monetary amounts are represented, what gets embedded and what gets linked— and the headers that govern that body. It is a lesson of small, very long-lived decisions: the name of a published field is contract for years, and getting monetary amounts wrong is paid for in lost cents. By the end you will have the canonical representation of every resource and the content negotiation rules that module 3 will implement.

1. What a representation is
2. Naming and type conventions
3. Nulls versus absent fields
4. Dates, times and time zones
5. Monetary amounts
6. Enumerations and booleans
7. Envelope or bare object
8. Relationships: embed or link
9. Selective hypermedia: designing _links
10. Expansion and sparse fieldsets
11. Content negotiation
12. Responses that are not JSON

Let us recall the distinction from 01-04: the resource is the conceptual entity (the coffee cof_001), and the representation is one of its concrete forms at a given moment. The same resource can be represented as JSON in English, JSON in Catalan, a PDF or a JPEG image, and they all share a URI.

Hence the rule already stated in 02-02: the format does not go in the URL, it is negotiated with headers. And hence too the importance of this lesson's decisions: the representation is what the consumer actually sees and programs against.

Aroma Store uses camelCase for every JSON field name: priceEuros, createdAt, tastingNotes, customerId.

None is better in the abstract. Aroma Store chooses camelCase because its main consumers are JavaScript (the SPA, Aroma Mobile with React Native, the Node.js server) and so the JSON object is used without translation. What is mandatory is not mixing them: {"priceEuros": 14.50, "created_at": "..."} is the kind of detail that poisons an API.

• No technical prefixes or cryptic abbreviations: name, not strName or nm.
• Id suffix for references: customerId, coffeeId. It makes clear that it is a reference and not the object.
• A unit suffix where there is one: priceEuros, weightGrams, durationSeconds. It wipes out the question "what unit is this in?" in one stroke.
• Plurals for arrays: tastingNotes, items, data.
• No is/has prefixes: the boolean is called active, soldOut, gift.
• Domain names, not table names: origin, not originFk.

Two hard rules:

1. A field's type never changes. If stock is a number, it cannot become "120" in another response. It is a breaking change (02-07) and an inexhaustible source of bugs, because "0" is truthy in JavaScript and 0 is falsy.
2. Identifiers are always string. Even though 5001 looks like a number, ord_5001 is an opaque string, and that protects you on the day the format changes.

Three possible states for a field, and you have to choose what each one means:

Aroma Store's rule: a resource's representation always includes the same fields, using null for whatever does not have a value yet. The only legitimate absences are (a) fields the client has excluded with fields= and (b) objects that were not requested with expand=.

Why this rule is worth it:

Two nuances:

• null is not used in arrays: a list with no elements is [], never null. That way the client can iterate over it without checking.
• In a PATCH with Merge Patch, null means "delete" (02-03). It is a deliberate asymmetry between input and output, and it has to be documented.

All dates and times go in ISO-8601 with an explicit time zone, in UTC (Z).

Important points:

• UTC in storage and in transport; local time only in presentation. The client formats according to the user's zone; the server never assumes Madrid.
• Watch out for daylight saving. Spain switches from +01:00 to +02:00; if you store local time, two orders placed in the small hours of the changeover can appear out of order or duplicated.
• Dates with no time (2027-01-31) for anything that is a calendar day, such as a batch's expiry. Giving it T00:00:00Z invites off-by-one-day errors from zone shifts.
• Consistent names: <something>At for instants, <something>Days for durations. Aroma Store avoids a bare timestamp.

The section where the most money is lost to a technical oversight. Never use binary floating point for money on the server.

JSON's number, when processed as an IEEE 754 double, cannot represent 0.1 exactly. Adding up a hundred order items accumulates error, and in accounting a one-cent discrepancy is a real problem.

Representation options:

Aroma Store's decision:

• In the representation: a number with exactly two decimals and the Euros suffix (14.50, 29.00). It is readable and direct for the clients, which only display it.
• On the server and in the database: integer cents or an exact decimal type. The conversion happens at the edge (03-05).
• Totals are always calculated by the server. The client never adds up amounts to present them as official: that is why the order includes an already calculated totalEuros.
• Currency: v1 is euros only and that is stated in the documentation. If more currencies ever appear, an optional currency field with the default value "EUR" will be added —a backwards-compatible change (02-07)— rather than restructuring the amounts.

A detail that surprises people: 29.00 in JSON may be serialised as 29 depending on the library, because JSON does not distinguish integers from decimals. That is acceptable —numerically they are equal— and the client formats with two decimals when displaying. If it bothers you, the alternative is the decimal string, with its cost.

Aroma Store's enumerated values go in lowercase snake_case, with stable and extensible values:

Rules of the contract:

• The value is never translated. status: "paid" is a machine identifier; the label the user sees is supplied by the client. If a human-readable text is needed tomorrow, a separate field is added (statusText), the value is not changed.
• The list can grow. The documentation warns from day one: handle an unknown value gracefully (the robustness principle, 02-01). Adding status: "returned" must not break anyone.
• The list does not shrink and values are not renamed. That really is breaking.
• No numeric codes. roast: 1 forces you to maintain a lookup table out of band and is illegible in a log.

A boolean should only be used when the concept is genuinely binary and permanently so. Many "booleans" end up turning into enumerations: approved: true/false does not cover "pending moderation", which is exactly why reviews have status and not approved. When in doubt, enumeration: extending an enumeration is backwards-compatible; turning a boolean into an enumeration is not.

For a collection, what gets returned?

Option A, a bare array:

Option B, an envelope (Aroma Store):

Aroma Store's decision: an envelope for collections, a bare object for elements.

The main reason is tolerance to change: if tomorrow you have to add total, _links or deprecation notices to a collection, with the envelope it is additive and with the bare array you would have to break every client. And we do not wrap individual elements ({"data": {...}}) because it adds noise without contributing anything: an element is already an extensible object.

The practical consequence for the client, which has to be documented well:

The pagination metadata that goes alongside total is decided in 02-06.

An order has a customer and items pointing at coffees. How much of that travels in the response?

Linking:

Embedding:

Aroma Store's criteria:

1. Embed what is almost always needed and is small and stable. The coffee's name and priceEuros in each order item are embedded, and the price is embedded frozen: the order's price is the one that applied on the day of purchase, not the current one. Here embedding is not an optimisation, it is business correctness.
2. Link what is large, changeable or sensitive. The full customer, a coffee's reviews, the invoice.
3. Never embed an unbounded collection. A coffee with 4,000 reviews cannot carry them inside: they are linked and paginated.
4. Everything else, on demand with expand (section 10).

This is what an Aroma Store order ends up looking like:

In 01-05 we fixed the target level: solid Richardson 2 with selective hypermedia. Let us pin down exactly what that means in the contract, because "selective" without rules turns into chaos.

What DOES carry links:

What does NOT carry links: elements inside a collection do not carry complete _links (only self), so as not to multiply the response's weight twentyfold; coffees carry no action links, because they have no state machine.

Link format. An object with href and, for actions, method:

It is the simplified HAL shape (01-05), but without adopting application/hal+json or _embedded: we stay with application/json, because we do not want to force clients to understand a complete hypermedia format.

The state-dependent action links of an order are the heart of selective hypermedia:

And the rule that makes this useful at all, written in the documentation: "if an action link is not present, that action is not possible right now; do not build it by hand". The SPA renders its buttons from _links instead of replicating the state machine, which is exactly what we were after.

The link URIs are relative to the host (/v1/orders/ord_5001). It is documented that way so that it works identically in production, in staging and locally.

The two escape valves announced in 02-01 for governing granularity.

It embeds a related resource on demand, saving calls:

Aroma Store's rules for expand:

• A comma-separated list: ?expand=customer,items.coffee.
• Only one level of depth is allowed (items.coffee yes; items.coffee.reviews no) to avoid uncontrollable queries.
• The original field stays: customerId does not disappear when customer is added. That way the client does not have to write two different access paths.
• Only documented relationships can be expanded; an unknown value returns 400 with invalid_parameter.
• A maximum of three expansions per request.

The client asks only for what it is going to use.

Rules:

• id is always included, whether asked for or not: without it the response is unusable.
• Fields that were not asked for are omitted (the only legitimate exception to the rule in section 3).
• An unknown field returns 400 with invalid_parameter, instead of being silently ignored: that way typos are caught.
• It is not combined with expand over the same relationship in v1, so as not to multiply the number of cases.

This connects directly with the over-fetching we discussed in 01-07 when comparing REST with GraphQL: fields and expand cover 90% of the real need without giving up HTTP caching or taking on the complexity of a query language. It is a well-designed REST API's answer to that argument.

And the cost, which has to be taken on with eyes open: every combination of parameters is a different URL and therefore a different cache entry. Multiplying variants reduces the cache hit rate (04-06).

This is the mechanism by which client and server agree on the representation. The client proposes with Accept-* headers, the server chooses and declares its choice with Content-* headers.

The client can express weighted preferences, from 0 to 1 (1 by default):

It reads: "I prefer JSON; failing that, XML; as a last resort, anything" and "I prefer Catalan; failing that, Spanish; failing that, English". The server walks the options by descending q and serves the first one it can produce.

Notice three things:

• tastingNotes comes translated, because it is marketing copy aimed at the end user. roast is not translated: it is an enumeration, a machine identifier (section 6).
• Content-Language: ca declares what was served; it is essential, because the client asked for two languages and needs to know which one it got.
• Vary tells intermediate caches that the response depends on those headers and that they must not serve the Catalan version to somebody asking for English. Forgetting Vary is a serious and subtle bug: it is detailed in 04-06.

Aroma Store's language contract: en, es and ca are served; the default language is en; if an unavailable language is requested, 406 is not returned, en is served and Content-Language: en is declared. It is a pragmatic decision: for content, an alternative language is better than an error.

Accept-Encoding: gzip, br allows compression. A catalogue of 137 coffees in JSON can go from 180 KB down to around 15 KB with gzip: it is the best cost/benefit optimisation in the entire API. It is enabled on the server or on the gateway and it does not change the contract. Performance details are in 04-06.

Besides application/json, you can define your own types that identify the exact shape of the representation:

The vnd. prefix marks vendor types. The second example is versioning by media type, one of the strategies we will compare in 02-07. Aroma Store does not use it —it versions in the path— but it is worth recognising: when requesting content from an API that versions this way, Accept: application/json will give you whichever version the server considers the default, which may not be the one you expect.

Not everything is JSON, and content negotiation is precisely what lets them coexist without dirtying the URIs.

The same resource, two representations:

Content-Disposition suggests the file name on download, and Accept-Ranges announces that partial downloads are supported, which is what enables the 206 from 02-04. And there is no URL with .pdf: it is the same resource.

Here it is the client that sends something that is not JSON. Two approaches:

a) Direct binary with PUT on the singleton /coffees/{id}/image:

It is clean, idempotent and needs no additional format.

b) multipart/form-data when you have to send a file and metadata at the same time:

Aroma Store's decision: option (a), because in v1 there is only one main image per coffee and the description is a field of the coffee itself. The upload contract:

• Supported formats: image/jpeg, image/png, image/webp. Anything else → 415.
• Maximum size: 5 MB. If exceeded → 413 with body_too_large.
• The response is JSON, even though the request was binary: the response describes the created resource, it does not return it.
• The image is served from the CDN, not from the API. The API stores and returns its URL.

• CSV for internal panel exports: Accept: text/csv on /v1/orders.
• text/event-stream for the live panel's SSE that we decided on in 01-07: it is another kind of negotiated response, with a persistent connection.

In both cases the rule is the same: the format is negotiated, the URI does not change.

• Mixing naming conventions. A camelCase API with two snake_case fields slips through review and afterwards cannot be removed without breaking clients.
• Returning dates with no time zone. "2026-03-14T10:30:00" is ambiguous; the bug shows up in March and in October, at the clock change.
• Doing money arithmetic in floating point. Store cents or exact decimals and convert at the edge.
• Translating the enumerations. status: "pagat" forces clients to maintain per-language tables. Machine values are not translated.
• Returning a bare array for collections. You are left with nowhere to put metadata without breaking the contract.
• Embedding large objects "because it is convenient". The response balloons, caching degrades and you end up exposing personal data where you should not.
• Forgetting Vary. With an intermediate cache, one user can receive the response in somebody else's language. It is the hardest bug in this lesson to reproduce.
• Putting the format in the URL. .json/.pdf duplicate identities; that is what Accept is for.
• Tip: write the ideal JSON by hand first. Before looking at the data model, write the response you would like to receive. It is the best defence against dumping tables.
• Tip: review every field by asking "who consumes this?". If there is no answer, remove it: every published field has to be maintained forever.

This is the JSON a team proposes for a review. Rewrite it according to Aroma Store's conventions and justify each change.

Aroma Mobile, with the app in Catalan and on a slow network, wants the detail of order ord_5001 with the customer's data included, but only the fields it renders on screen (id, status, totalEuros, createdAt).

a) Write the complete curl request with all the relevant headers. b) Write the server's response with its headers. c) Explain why Vary is needed and what exactly would happen if it were omitted.

For each relationship, decide whether it is embedded, linked or offered via expand, and justify it with the criteria from section 8:

1. The coffee's name inside an order item.
2. The 4,000 reviews of cof_001 on the coffee's detail page.
3. The full customer inside an order, in the internal panel.
4. The shipping address inside an order.
5. A coffee's average rating in the catalogue listing.
6. A customer's payment history on their record.

Solution 1

Solution 2

a)

b)

Note: status stays in its machine form because it is an enumeration, not translatable text; the app turns it into "Pendent de pagament" when rendering. And customer appears even though it is not in fields because the expansion is explicit: it is documented that way so that it does not surprise anyone.

c) Vary tells intermediate caches (CDN, corporate proxy, gateway) which request headers influence the response. Without it, the cache would store this response under the plain "URL" key. The concrete consequence: the next user who requested the same order with Accept-Language: en would receive the stored Catalan version; and a client that did not support Brotli could receive a body compressed with br that it cannot decompress, so the response would be unreadable rubbish.

Solution 3

The representation is what the consumer actually sees, and it is now designed from top to bottom: camelCase, identifiers as opaque strings, fields always present with null for whatever has no value yet and [] for empty lists, ISO-8601 dates in UTC, amounts in euros with two decimals and exact cents internally, extensible untranslated snake_case enumerations, and the {"data": [...], "total": n} envelope for collections against the bare object for elements. We have fixed what gets embedded —what is small, stable and frozen, such as the name and price of an item— and what gets linked, exactly what the _links of level 2 selective hypermedia look like, and how expand and fields give each consumer the granularity it needs without giving up REST. And we have settled content negotiation with Accept, Accept-Language and Accept-Encoding, with Vary as an indispensable piece, including the representations that are not JSON: the PDF invoice and image uploads.

One piece remains that we have been postponing and that shows up as soon as the catalogue grows: what happens when a collection has 4,000 elements. In the next lesson, 02-06 Filtering, Sorting, Pagination and Search, we will design Aroma Store's large collections: the conventions for filters and ranges, stable sorting, the three pagination models with their comparison table and the deep paging problem, where the pagination metadata travels —total and the Link header—, text search and the default limits that protect the API.