HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) is the constraint that makes an API fully RESTful: each response carries hypermedia links describing the state transitions available from the current resource. Clients discover what they can do next by following links, instead of hardcoding URL templates.

Why it matters

Without HATEOAS, a client must know every endpoint and how to build its URLs in advance. Any change to the URL scheme breaks clients. With HATEOAS, the server owns the URLs and advertises them in each representation, so clients navigate by link relations (self, next, cancel) rather than string concatenation. This is level 3, the top level of the Richardson Maturity Model.

How it works

• A representation includes a set of links, each with a relation (rel) and a target URL (href).
• The client picks an action by its relation, not by guessing the URL.
• Available links reflect current state: a shipped order exposes track, a pending order exposes cancel.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel" },
    "pay":    { "href": "/orders/42/payment" }
  }
}

Hypermedia formats

Several media types standardize how links are expressed so generic clients can parse them:

• HAL, _links and _embedded objects (shown above).
• JSON:API, links and relationships members.
• Siren, entities with links and actions (including HTTP method and fields).
• Collection+JSON, templated forms for queries and writes.

Trade-offs

HATEOAS decouples clients from URL structure and enables server-driven workflows, but it adds payload size and client complexity: few client libraries follow links automatically, so teams often hand-code navigation anyway. Most production APIs stop at maturity level 2 (verbs plus status codes) and adopt hypermedia selectively where workflows are genuinely state-driven.

GET /orders/42 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "status": "shipped",
  "_links": {
    "self":  { "href": "/orders/42" },
    "track": { "href": "/orders/42/shipment" }
  }
}