Hypermedia (HATEOAS)

Overview

Hypermedia as the Engine of Application State (HATEOAS) is the top level of the REST maturity model. Responses carry the links a client can follow next, so the server, not the client, controls navigation and which operations are currently available.

How it works

A resource representation includes a links section keyed by relation name. Here is an order in HAL style.

GET /orders/42
{
  "id": 42,
  "status": "PENDING",
  "_links": {
    "self":   { "href": "/orders/42" },
    "pay":    { "href": "/orders/42/payment" },
    "cancel": { "href": "/orders/42" , "method": "DELETE" }
  }
}

After payment the status becomes PAID and the pay link disappears while a refund link may appear. A client checks for the pay relation instead of re-implementing the rule that only pending orders can be paid. Paginated collections expose next and prev links, so clients never compute offsets.

Pitfalls

• Treating links as decoration while clients still build URLs, which gives the cost without the benefit.
• Emitting links regardless of authorisation, leading to 403 surprises.
• Undocumented or unstable relation names. Relations are the contract; version them.
• Chatty navigation requiring many hops; embed related resources where needed.
• Adopting it for internal services where the coupling is acceptable anyway.

Key takeaways

• Links express what the client can do next, based on current state.
• Clients depend on relation names and media types, not URL shapes.
• Worth the cost for long-lived, widely consumed APIs.
• Keep link generation centralised and permission-aware.