HATEOAS

HATEOAS — Hypermedia as the Engine of Application State — is the constraint that distinguishes a fully RESTful API from a plain HTTP/JSON API. Responses include hypermedia links that tell the client which actions are available next, so the client discovers and drives the application by following links rather than by hard-coding URLs and rules. It is the highest level of Richardson's REST maturity model.

How It Works

Each resource representation embeds links to related resources and permitted state transitions. An order response might include a self link, a cancel link only when the order is cancellable, and a pay link only when payment is due. The client inspects the links present rather than computing them from business logic it has duplicated locally. The set of links acts as the state machine: the server advertises valid transitions, and the client follows them.

Standardized media types formalize this. HAL uses a _links object; JSON:API uses links and relationships; Siren adds actions with methods and fields. A client written against the media type can traverse any compliant API by following relations like next, self, or author.

When to Use It

HATEOAS pays off for long-lived, evolvable APIs with multiple clients, for workflow-driven resources where available actions depend on state, and when you want to change URL structures without breaking clients (they follow links instead of building URLs). Pagination is a common, practical entry point: returning next/prev links so clients never construct page URLs themselves.

Trade-offs

Full HATEOAS is rare in practice. It adds payload size and complexity, and most client developers still read documentation and hard-code endpoints, negating the discoverability benefit. Tooling and code generators favor static contracts (OpenAPI) over runtime link-following. The cost/benefit only justifies full hypermedia for certain large public or workflow-heavy APIs; many teams adopt lightweight links (pagination, related resources) without going all in.

Related Patterns

Pagination is the most widely used slice of HATEOAS. The link-driven transitions implement a state machine over a resource's lifecycle. API versioning addresses contract evolution that HATEOAS aims to reduce. A backend-for-frontend can tailor hypermedia to specific clients.

Example

{
  "id": 1042,
  "status": "awaiting_payment",
  "total": 59.90,
  "_links": {
    "self":   { "href": "/orders/1042" },
    "pay":    { "href": "/orders/1042/payment", "method": "POST" },
    "cancel": { "href": "/orders/1042", "method": "DELETE" }
  }
}

Because the order is awaiting payment, the server advertises pay and cancel; once paid, those links disappear and a ship link might appear, guiding the client through valid transitions.