HATEOAS and Hypermedia
Understand one of REST's most frequently misunderstood constraints: Hypermedia As The Engine Of Application State.
What Is HATEOAS?
HATEOAS means Hypermedia As The Engine Of Application State.
It is part of REST's uniform-interface constraint. Instead of requiring clients to hard-code every possible transition, the server provides hypermedia controls that communicate available next actions.
For example, an order representation might contain links to itself, its customer, payment operation, cancellation operation, and shipment.
A truly hypermedia-driven client can discover available transitions from representations instead of depending entirely on undocumented URI conventions.
{
"id": "order_42",
"status": "pending",
"total": 1999,
"_links": {
"self": {
"href": "/orders/order_42"
},
"pay": {
"href": "/orders/order_42/payment",
"method": "POST"
},
"cancel": {
"href": "/orders/order_42/cancellation",
"method": "POST"
}
}
}HATEOAS as a State Machine
Hypermedia and State
HATEOAS becomes especially powerful when resources have states.
For example, an order might transition from pending to paid, shipped, and delivered. A pending order may expose a pay link, while a shipped order should not expose a cancellation operation if cancellation is no longer legal.
The server controls which transitions are available based on current state, user permissions, and business rules.
This makes the API representation a discoverable description of the client's next possible actions.
HATEOAS vs Typical JSON REST APIs
Is Every JSON REST API HATEOAS?
No.
An API can use HTTP verbs, resource-oriented URLs, JSON, status codes, and stateless requests while still not implementing HATEOAS.
For example, if a client is programmed with /orders/{id}/payment and knows this URI independently of server responses, it is not relying on hypermedia to discover the transition.
HATEOAS is often omitted because it increases implementation and client-design complexity. Nevertheless, understanding it is important because it is a formal REST constraint and can be valuable for discoverable, state-driven APIs.
What does HATEOAS stand for?