What is HATEOAS, and do you need it?
Quick Answer
HATEOAS (Hypermedia As The Engine Of Application State) means API responses include links to the actions and related resources available next, so a client can navigate the API by following links rather than hard-coding URLs. It's level 3 of the Richardson Maturity Model. In practice most APIs skip it — the cost rarely pays off for a known first-party client.
HATEOAS is the idea that each API response carries links telling the client what it can do next and where the related resources are, so the client walks the API by following links instead of building URLs itself. It's the top of the REST maturity model. The theory is nice — the server owns the URLs and the client is decoupled — but in reality, first-party clients still code against a documented contract and don't dynamically follow links, so most teams don't implement it fully. I'd include practical links like pagination next/prev and stop there.
- An order response includes
{ "_links": { "self": "/orders/5", "cancel": "/orders/5/cancel", "customer": "/customers/42" } }. - Argument for: the server controls the URL structure and available transitions; clients are more decoupled; discoverability.
- Argument against: real clients still code against a documented contract; adds payload and complexity; tooling support is weak.
- Sensible middle ground: include a few useful links (pagination
next/prev) without going full hypermedia.