HATEOAS – Hypermedia as the Engine of Application State
When designing RESTful APIs, we often focus on resources, endpoints, and HTTP verbs — but we tend to overlook one of the most powerful ideas that REST was built upon: hypermedia. This is where HATEOAS (Hypermedia as the Engine of Application State) comes in.
At its core, HATEOAS means that a client interacts with an API through hypermedia links provided dynamically by the server, rather than relying on hardcoded URLs or prior knowledge of the API structure.
“We simply embed enough information in our responses that the client can intelligently choose what action to take next using only the contents of the HTTP response.”
— restfulapi.net/hateoas
Why HATEOAS?
Traditional REST APIs often look like this:
/api/orders/api/orders/{id}/api/orders/{id}/items
Clients must know these routes ahead of time. Any change to an endpoint, or the introduction of a new workflow, may break existing clients.
HATEOAS solves this problem by embedding links and relations directly in the server’s responses. This way, the client doesn’t need to know where to go next — the server tells it.
The goal, as described is to create REST services that are easier to understand, more self-descriptive, and more adaptable to change.
A Simple Example
Here’s what a HATEOAS-enabled response might look like using the HAL format:
{
"id": 42,
"name": "Notebook",
"price": 19.99,
"_links": {
"self": { "href": "/api/products/42" },
"update": { "href": "/api/products/42", "method": "PUT" },
"delete": { "href": "/api/products/42", "method": "DELETE" },
"reviews": { "href": "/api/products/42/reviews" }
}
} The client can use the _links object to decide what to do next — update the product, delete it, or fetch its reviews — without knowing the endpoint structure beforehand.
Benefits of HATEOAS
- Discoverability
Clients can explore the API through the links provided by each response, similar to how users navigate the web. - Decoupling between client and server
The client doesn’t need to hardcode URLs or understand the full API upfront. Changes in the server’s structure won’t necessarily break clients. - Easier evolution of APIs
As workflows change, you can simply expose new relations and retire old ones — without forcing client updates. - Self-documenting responses
Instead of external documentation, the API response itself explains available actions.
Challenges and Drawbacks
While HATEOAS brings elegance and flexibility, it’s not a free lunch.
- Increased implementation complexity.
You need to generate and manage link relations dynamically. - Limited support in client libraries.
Not all HTTP clients natively understand hypermedia formats. - Overhead and verbosity.
Embedding links adds extra data to every response, which may not be ideal for very high-volume or performance-critical APIs.
Hypermedia Formats
Several hypermedia representations have emerged over time, each offering a different balance between simplicity and expressiveness:
| Format | Description | Spec |
|---|---|---|
| HAL (Hypertext Application Language) | Lightweight and easy to implement. Links under _links. | hal_specification |
| SIREN | Supports actions and entities, ideal for rich hypermedia interactions. | sookocheff.com |
| JSON-LD + Hydra | Adds semantic meaning to data and actions. | hydra-cg.com |
| Collection+JSON, JSON:API | Provide partial hypermedia features but less focused on HATEOAS purity. | — |
Each format defines its own conventions for linking and describing state transitions. HAL remains the most widely used for its simplicity and tooling support.
Implementing HATEOAS in Practice
Depending on your stack, there are frameworks and libraries that make implementing HATEOAS straightforward:
Java / Spring Boot:
Spring HATEOAS provides annotations and link builders that integrate with standard controllers.
@GetMapping("/products/{id}")
public EntityModel<Product> one(@PathVariable Long id) {
Product product = repository.findById(id)
.orElseThrow(() -> new ProductNotFoundException(id));
return EntityModel.of(product,
linkTo(methodOn(ProductController.class).one(id)).withSelfRel(),
linkTo(methodOn(ProductController.class).all()).withRel("products"));
} .NET Core:
You can dynamically build links in controllers using Url.Link() or custom middleware, returning objects that follow the HAL or JSON:API structure.
var product = new {
Id = 42,
Name = "Notebook",
Price = 19.99,
_links = new {
self = new { href = Url.Link("GetProduct", new { id = 42 }) },
update = new { href = Url.Link("UpdateProduct", new { id = 42 }), method = "PUT" }
}
}; Node.js / Express:
Middleware like express-hateoas-links can automatically append link metadata to responses.
When Not to Use HATEOAS
Despite its benefits, HATEOAS isn’t always the right choice.
Consider skipping it if:
- You’re building a simple, internal API used by a single known client.
- Your performance budget is tight and payload size matters.
- The workflow is fixed and unlikely to change, making dynamic navigation unnecessar
Conclusion
HATEOAS is one of the most elegant yet underused principles of REST.
It transforms a static set of endpoints into a navigable API, where clients can discover actions dynamically through links — just like browsing the web.
If you’re designing APIs that need long-term stability, discoverability, or version flexibility, consider adding hypermedia links to your responses.
It might just make your API smarter and your clients simpler.
Final Thoughts
It’s important to note that HATEOAS is not an official standard — it’s a guiding principle within the broader REST architecture. While formats like HAL, SIREN, and JSON-LD have emerged to implement it, there’s no single, universally accepted specification.
However, as APIs continue to evolve toward greater discoverability, flexibility, and resilience to change, HATEOAS may one day become a de facto standard for truly RESTful systems — not just a theoretical ideal.