In the previous lesson we saw that REST is met in degrees, and that almost no real API is fully RESTful. That leaves a very practical open question: how is that degree measured? In 2008 Leonard Richardson proposed a four-level model that has become the industry's standard vocabulary. In this lesson we will work through the four levels by rewriting the same Aroma Store operation — creating an order — at each of them, so that the progression can be seen with your own eyes. We will then get into HATEOAS, the highest and most disputed level, look at real hypermedia formats such as HAL and JSON:API, and close with an honest debate about when it pays to go all the way to the top and when it does not.

1. What the maturity model is for
2. Level 0: the swamp of POX
3. Level 1: resources
4. Level 2: HTTP verbs and status codes
5. Level 3: hypermedia controls (HATEOAS)
6. The four levels at a glance
7. What HATEOAS is and what problem it solves
8. Hypermedia formats: HAL, JSON:API and Siren
9. The honest debate: why does almost nobody reach level 3?
10. Criteria for deciding your level

Leonard Richardson presented this model at the QCon conference in 2008, and Martin Fowler popularised it in a 2010 article. Its virtue is twofold:

• It offers a shared vocabulary: saying "we are at level 2 and we do not plan to go higher" communicates an entire architectural decision in a few words.
• It turns a binary, sterile argument ("is this REST or not?") into a progressive scale you can reason about.

Two warnings before we start:

1. It is not Fielding's and it is not normative. It is a descriptive model, useful for diagnosis, not an exam you have to pass.
2. Moving up a level is not automatically better. Each level has a cost. The goal is to choose with judgement, not to maximise your score.

POX stands for Plain Old XML, although today the swamp is more likely to be made of JSON. Its hallmarks:

• A single endpoint for everything.
• A single method, almost always POST.
• The operation to be executed goes inside the body.
• HTTP is used as a mere transport tunnel: its methods, its codes and its caching are ignored entirely.

This is how Aroma Store would create an order at level 0:

And the response:

And this is how it would look up that same order:

What is wrong with it, in concrete, measurable terms:

This is, essentially, RPC over HTTP. It is exactly what SOAP did (lesson 01-06) and what today... GraphQL does, which also uses a single endpoint and POST (lesson 01-07). With one important difference: GraphQL does it deliberately, with a typed contract and its own tooling that compensates for what it gives up. Level 0 is usually accidental.

The first leap: stop having a single endpoint and give every thing in the domain its own identity. You no longer talk to "the API", you talk to specific resources.

Looking that order up, at level 1:

What has been gained:

• Each order has its own URI: /v1/orders/ord_5001. It can be linked, recorded in logs and routed distinctly.
• The load can be split by resource: orders to some servers, the catalogue to others.
• The API is far more comprehensible when you read a log or a trace.

What is still missing:

• POST is still used for everything, even for reading. No caching, and no distinction between reads and writes.
• The verb is still in the body (action).
• Status codes are still unused.

Level 1 is a transitional state: many people reach it while reorganising an old API and stop halfway. Recognising it has diagnostic value: if your URLs are good but everything is a POST, you are here.

Here is the big leap, and where the vast majority of professional APIs live, including the one we will build in module 3. It consists of using the protocol as it was designed: the verb indicates the intent and the status code indicates the result.

Creating an order:

Note three details that did not exist at the previous levels:

• 201 Created instead of 200 OK: it states precisely that something new has been created.
• Location: it says where the resource ended up, without the client having to compose the URL.
• Cache-Control: no-store: an explicit instruction that nobody should store an order's data.

The remaining operations on the same resource, now without any action field:

And errors are expressed in the protocol itself:

The code 422 says "I understood your request but I cannot process it because of its content"; the body gives the detail in a form the developer can read. Machines and humans, each with their own information.

Benefits accumulated at level 2:

• Real caching on GETs, with a direct impact on cost and latency.
• Idempotency on GET, PUT and DELETE: retries are safe.
• Automatic monitoring: any tool counts the 5xx without knowing anything about coffee.
• A minimal learning curve for consumers: if they know HTTP, they already know your API.

The last level adds links to the responses: the server returns not only data, but also which transitions are possible from the current state.

The interesting part happens when the state changes. Once paid and shipped, the same GET /v1/orders/ord_5001 request returns different links:

pay and cancel have gone — they are no longer possible — and tracking, invoice and return have appeared. The client does not need to know the order's state machine: it simply has to render the buttons corresponding to the links it receives. If tomorrow Aroma Store decides that shipped orders can also be forwarded as a gift, a new link appears and clients able to interpret it will show it without deploying a new version.

HATEOAS stands for Hypermedia As The Engine Of Application State. Translated: the client moves through the application by following the links the server gives it, just as you browse a website without knowing its URLs by heart.

The browser analogy is the most illuminating one. When you enter an online shop:

• You do not type out shop.example/cart/add?product=123 by hand.
• You click "Add to basket", a link or a form that the page itself gave you.
• If the product is out of stock, that button simply is not there.

The browser knows nothing about coffee or baskets: it knows how to follow links and submit forms. HATEOAS aims to bring that same capability to programmatic clients.

The problem it solves is coupling to URLs and to business rules:

If every API invents its own way of expressing links, half the benefit is lost. That is why standardised formats exist. Let's look at the same Aroma Store order in the two most widely used ones.

It is the lightest and the most widely adopted. It adds two conventions: _links for links and _embedded for embedded resources. Its content type is application/hal+json.

HAL's advantage: it is a very thin layer over the JSON you already had. Its limitation: the links do not say which method to use or which fields to send; that has to be documented separately or extended by convention.

This is a far stricter and more complete format, with its own specification and the content type application/vnd.api+json. It standardises not only links, but the data structure, relationships, the inclusion of related resources, pagination, filtering and errors.

Noticeable differences compared with HAL: the data goes under data with an explicit type and id, attributes are separated from relationships, and included allows complete related resources to be sent in the same response (which attacks the same "too many requests" problem that motivates GraphQL). The price is verbosity and a real learning curve.

It goes one step further and models actions with all their details: method, content type and expected fields.

With Siren, a generic client could generate a form from the response, just as a browser does with HTML. It is the most faithful to the spirit of HATEOAS and the least used in practice.

There is also a minimal alternative with no specific format: the HTTP Link header, standardised in RFC 8288 and widely used for pagination:

It is low-cost hypermedia and perfectly legitimate. We will come back to it when we talk about pagination in 02-06.

Fielding was blunt in 2008: an API without hypermedia controls is not REST. And yet almost no commercial API you use day to day implements HATEOAS fully. It is worth understanding why, without falling into either dogmatism or disdain.

Arguments in favour of HATEOAS:

• It decouples the client from the URLs, letting you reorganise them without breaking anything.
• It centralises business logic on the server: the state machine is not replicated in every client.
• Discoverability: a new developer can explore the API by navigating from the root.
• It is especially valuable with many clients you do not control and flows with complex states.

Arguments against, or at least qualifying it:

• Real clients are not generic. Aroma Mobile has a screen designed specifically for paying an order; whether the pay link is present or not does not save the app from having to know that flow, its fields and its design.
• There is no universal client. The browser works because HTML defines links and forms in a standard way and there is a human interpreting them. With JSON there is no equivalent: the client needs to know that rel: "pay" means pay, which reintroduces semantic coupling.
• Implementation and maintenance cost on both sides: generating links conditioned by state and permissions is not trivial.
• Heavier responses, with an impact on mobile clients.
• Consumer teams tend to ignore the links and go on building URLs by hand, so you pay the cost without getting the benefit.
• Scarce tooling: compared with the OpenAPI ecosystem, support for hypermedia is limited.

The industry's position, which is also the one this course takes:

• Level 2 is the de facto professional standard. A well-built level 2 API — clean URIs, correct verbs, meaningful status codes, caching and well-modelled errors — is an excellent API.
• Adding partial hypermedia is cheap and worthwhile: a self link, pagination links and links to related resources deliver real value at minimal cost. It is what nearly everyone does, and it is what we will do with Aroma Store.
• Full HATEOAS is reserved for cases with rich state flows and diverse consumers: payment gateways, open banking, long-lived government APIs.

Concrete questions to place yourself:

Aroma Store's decision: a solid level 2 with selective hypermedia. Specifically:

• A self link on every resource.
• Pagination links on collections (the Link header).
• Links to related resources (customer, coffee) so that URLs never have to be composed.
• State-dependent action links only on orders, which is where the state machine is real and where the internal panel and the app benefit.

It is a conscious decision, with its reasons written down. That is exactly what is expected of a professional design.

• Treating the model as an exam. Nobody gives you a prize for reaching level 3. The prize goes to an API that works well and can be maintained.
• Believing you are at level 2 because you use GET and POST. If you return 200 OK for errors or put verbs in your URIs, you are not.
• Implementing _links without judgement. Always returning the same links, regardless of state and permissions, is decorative: it contributes nothing and adds weight.
• Inventing your own hypermedia format. If you are going to do it, use HAL or JSON:API: you will get libraries, documentation and developers who already know them.
• Mixing formats. Using HAL's _links alongside JSON:API's data/attributes structure confuses both tools and people.
• Confusing HATEOAS with "returning absolute URLs". An imageUrl field is not a hypermedia control; a link with a relation (rel) expressing a possible transition is.
• Tip: if you are starting today, aim for an impeccable level 2 and add self and pagination links from day one. Moving up later is easy; cleaning up a badly designed API is not.

For each API, state which Richardson level it is at and justify it with two reasons:

1. POST /service with body {"method":"listCoffees"}, response always 200 OK.
2. GET /v1/coffees/cof_001 returns 200 OK; POST /v1/coffees returns 201 Created with Location; GET /v1/coffees/cof_999 returns 404 Not Found.
3. POST /v1/coffees/search, POST /v1/coffees/create, POST /v1/coffees/delete, all with 200 OK.
4. Like number 2, but every response includes _links with self, reviews and, if there is stock, addToCart.

This Aroma Store operation is at level 1. Rewrite it at full level 2 (request, status code and relevant headers), and explain each decision.

Current response: 200 OK with {"success": true}.

The Aroma Store review resource has three states: pending_moderation, published and rejected. The rules are:

• A pending review can be approved or rejected (by a moderator only), and its author can edit it.
• A published review can be replied to by the shop team and its author can delete it.
• A rejected review allows no actions, but the reason can be seen.

Design the response in HAL format for all three states, as seen by a moderator.

Solution 1

1. Level 0. A single endpoint (/service), the operation goes in the body, everything by POST and always 200.
2. Level 2. There are URIs per resource, methods are used according to their semantics and the status codes are correct (201 with Location, 404 when it does not exist). There are no links, so it is not level 3.
3. Level 1. URIs exist under /v1/coffees, but the verb is still in the path and everything goes by POST with 200: neither the methods nor the codes are used.
4. Level 3. It meets everything from level 2 and additionally incorporates hypermedia controls conditioned by state (the add-to-cart link only appears if there is stock).

Solution 2

Decisions:

• The verb moves to the HTTP method: deleting is DELETE, not an action field in the body.
• The cart item becomes a resource in its own right with an identifiable URI (/v1/carts/crt_77/items/cof_002), which also allows it to be looked up or its quantity modified with PATCH.
• DELETE is idempotent: if the request is retried after a network failure, the result is the same. With the previous POST there was no such guarantee.
• 204 No Content indicates success with no body, instead of a redundant {"success": true}. If we wanted to return the updated cart to save the client a request, 200 OK with the complete cart would also be correct: it is a legitimate design decision.
• If the item does not exist, the response is 404 Not Found; if the cart belongs to another customer, 403 Forbidden.

Solution 3

State pending_moderation (moderator's view):

State published:

State rejected:

Key points of the solution:

• The links change with the state: that is where the value of HATEOAS lies. The moderation panel can render its buttons from the links without knowing the state machine.
• The links also depend on who is asking: the author would see edit and delete instead of approve and reject. A hypermedia response reflects permissions, not just state.
• Actions are modelled as sub-resources (/approval, /rejection, /replies) that you POST to, avoiding verbs in the URIs.
• The self link is always there, and rejectionReason only appears when it makes sense.

The Richardson maturity model offers a precise vocabulary for talking about how RESTful an API is: from level 0 — one endpoint, everything POST, HTTP as a mere tunnel — to level 3, where responses include the hypermedia controls that guide the client. We have seen the same Aroma Store operation rewritten at all four levels and confirmed that the decisive leap is level 2: resources with their own URI, verbs with their semantics and correct status codes, which is where you get caching, idempotency and monitoring for free. HATEOAS delivers real decoupling and centralises the state machine, but it has a cost that many teams never recoup; that is why Aroma Store will adopt a solid level 2 with selective hypermedia, and with the reasons written down.

With the REST model now thoroughly understood, it is time to place it against the alternatives. In the next lesson, REST vs. SOAP, we will take a close look at the style that dominated enterprise web services: its XML envelope, its WSDL contract, its WS-* stack, and we will compare both approaches side by side on the same Aroma Store case to understand when each still makes sense today.