What is HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint where API responses include links to related actions and resources. Instead of the client hardcoding URLs, it discovers available operations by following links in responses.

How it works

A response includes a links section with URLs for related operations:

{
  "id": 42,
  "name": "Alice",
  "links": {
    "self": "/api/users/42",
    "orders": "/api/users/42/orders",
    "delete": "/api/users/42"
  }
}

The client doesn't need to know the URL structure in advance — it follows links from the API root. If the server changes its URL scheme, clients that follow links adapt automatically.

Why it matters

HATEOAS decouples clients from server URL structure. In theory, a client only needs to know the root URL. In practice, almost no REST API fully implements HATEOAS — the tooling overhead is high, and most APIs simply document their URLs. GitHub's API is a notable exception, providing url fields on every resource. The concept influenced hypermedia API formats like HAL and JSON:API.

See How REST Works for HATEOAS in the context of Fielding's original REST constraints.