Stop 09 · API DesignTopics · 5/12

HATEOAS

In short

Most APIs make the frontend hardcode every URL and every rule about what's allowed. HATEOAS flips that: each response tells the client what it can do next, as links.

Hypermedia As The Engine Of Application State — a REST maturity level where responses include links to related actions/resources, so clients can navigate the API dynamically instead of hardcoding URLs.

The blob character follows arrow signboards on a railway platform.

Think of it like this

Signboards at the railway station

You don't memorise Howrah station's layout. You get off the train and follow the boards: exit, platform 9, ticket counter. HATEOAS responses carry those boards. An order says 'pay here' or 'cancel here', and shows only the boards that apply right now.

Watch it happen

GET /orders/42 response

order 42

status: pending

total: 1499

_links

self

pay

cancel

1/4The response starts with the data: order 42 is pending and costs 1,499 rupees.

The big ideas

What you need to know

Links ride with data

Each response carries URLs for related actions, like pay, cancel or next page, under a field such as _links.

State decides the links

A shipped order has no cancel link. The client shows buttons based on links, not copied business rules.

Clients follow, not build

The frontend reads link.href instead of gluing strings, so you can move URLs without breaking it.

Use the useful parts

Full HATEOAS is rare in practice. Pagination links and action links are the parts most teams actually adopt.

See it in code

Walk through the code

json

1{2  "id": 42,3  "status": "pending",4  "total": 1499,5  "_links": {6    "self":   { "href": "/orders/42", "method": "GET" },7    "pay":    { "href": "/orders/42/payment", "method": "POST" },8    "cancel": { "href": "/orders/42", "method": "DELETE" }9  }10}

1/3The usual order data. Nothing special yet.

This loosely follows the HAL style. A shipped order would return only self, and the app would hide its Pay and Cancel buttons.

Save yourself the pain

Common mistakes

Oops

Hardcoding '/orders/' + id + '/payment' all over the frontend.

Do this instead

Read the href from _links. When the backend changes the URL, the app keeps working.

Oops

Returning every possible link, whatever the state.

Do this instead

Only include actions that are valid right now. That's the whole point: links describe what's allowed.

Your mission

Add action links

~20 min

Quick check

An order has shipped. What should a HATEOAS response do with the cancel link?

Go deeper

1Read an example HATEOAS response and identify the embedded links.
2Understand this is the most 'pure' form of REST but rarely fully implemented in practice.
3Recognize this concept if it comes up in interviews, even if you don't use it day-to-day.