HATEOAS is a constraint of REST that sets it apart from other network application architectures.
It allows clients to dynamically navigate APIs using hypermedia links without requiring prior knowledge beyond a basic understanding of hypermedia itself.
At its core, HATEOAS enables the server to guide the client by embedding links within responses.
This theoretically decouples clients from servers, allowing the latter to evolve independently.
But here’s the catch: HATEOAS doesn’t work for APIs in the real world.
The Ideal vs. The Reality
Let’s compare two approaches: one that follows HATEOAS and one that follows a typical JSON API design.
HATEOAS in Action
Consider a GET request to fetch a bank account:
GET /accounts/12345 HTTP/1.1
Host: bank.example.com
The server responds with hypermedia links embedded in the HTML:
<html>
<body>
<div>Account number: 12345</div>
<div>Balance: $100.00 USD</div>
<div>Links:
<a href="/accounts/12345/deposits">deposits</a>
<a href="/accounts/12345/withdrawals">withdrawals</a>
<a href="/accounts/12345/transfers">transfers</a>
<a href="/accounts/12345/close-requests">close-requests</a>
</div>
<body>
</html>
When the account is overdrawn, the response dynamically changes:
<html>
<body>
<div>Account number: 12345</div>
<div>Balance: -$50.00 USD</div>
<div>Links:
<a href="/accounts/12345/deposits">deposits</a>
</div>
<body>
</html>
The client doesn't need to know anything about account states—it just follows the links provided.
JSON API Without HATEOAS
Now, compare this with a more typical JSON API response:
{
"account": {
"account_number": 12345,
"balance": {
"currency": "usd",
"value": -50.00
},
"status": "overdrawn"
}
}
Here’s the issue: the client needs out-of-band knowledge (from documentation) to understand what status: "overdrawn" means and what actions are allowed.
The client must also know endpoint URLs, which are not embedded in the response.
Why HATEOAS Fails in APIs
In theory, HATEOAS should make APIs self-explanatory and adaptable.
In practice, it doesn’t work because:
- Few Good Tools Exist – Most API frameworks don’t have strong support for HATEOAS.
- Clients Don’t Use It – API consumers rarely build clients that dynamically discover actions from responses.
- Developers Still Need API Documentation – Since no standard conventions exist for representing actions, developers must rely on external documentation.
- Versioning Is Still Needed – HATEOAS was meant to allow seamless API evolution, but clients still break when APIs change.
Even Roy Fielding, the creator of REST, has criticized the misuse of the term “REST API” for JSON-based RPC-like designs.
REST Is Still Useful, But Not Sacred
REST is great, but it’s not the only option. While RESTful principles like statelessness and resource-based interactions are valuable, HATEOAS is largely impractical.
Most modern APIs function more like RPC-over-HTTP than true RESTful systems.
If you’re building an API today, don’t get stuck on HATEOAS.
Instead, focus on clear documentation, strong API contracts, and developer experience.
Final Thoughts
REST isn’t dead, but it’s not a religion.
The industry has moved beyond HATEOAS, and that’s okay.
Choose the API architecture that best fits your needs—whether it’s REST, GraphQL, or gRPC.
I’ve been working on a super-convenient tool called LiveAPI.
LiveAPI helps you get all your backend APIs documented in a few minutes
With LiveAPI, you can quickly generate interactive API documentation that allows users to execute APIs directly from the browser.
If you’re tired of manually creating docs for your APIs, this tool might just make your life easier.
Top comments (0)