CodePark/ questions / REST resource design
START PRACTICINGPRACTICE
Backend question · HTTP & API design › REST resource design

What is HATEOAS, and why do most JSON APIs only partly adopt it?

{
  "id": 981,
  "status": "pending",
  "_links": {
    "self": { "href": "/orders/981" },
    "cancel": { "href": "/orders/981/cancellations", "method": "POST" },
    "customer": { "href": "/customers/42" }
  }
}

HATEOAS (Hypermedia As The Engine Of Application State) is a REST rule: each response contains links that show what the client can do next. In the example, the cancel link appears only while the order can still be cancelled. So the client does not hard-code URLs or business rules.

The benefit: the server can change URLs and workflows without breaking clients that follow the links. It works the same way a browser follows links on a web page.

In practice, most API clients are written from documentation or an OpenAPI spec (a file that describes every endpoint). These clients build URLs themselves. So full hypermedia adds bigger responses and more design work for little gain.

Many APIs use only the useful parts:

  • self links to the resource itself.
  • Pagination links like next.
  • Links to related resources.
  • Responses include links to the actions the client can take next.
  • Clients follow the links instead of hard-coding URLs.
  • The server can change URLs and workflows without breaking clients.
  • Most APIs adopt it partly: self links, pagination links and related links.