What is HATEOAS?

HATEOAS is an acronym formed from the initials of the words "Hypermedia as the Engine of Application State" and is one of the key architectural constraints of a true REST API. With HATEOAS, clients can interact with a REST API dynamically without having prior, hardcoded knowledge of the URI structure or available endpoints.

💡 Summary (TL;DR):
What is HATEOAS?: It's the highest level of REST maturity where the server returns hypermedia links along with data to guide the client on what actions are possible.
Core Benefit: Complete decoupling of the client from the server's URL schemes. The client navigates the API using relations (rel) and links, not hardcoded path strings.
Motto: Decouple clients from server URIs using dynamic hypermedia links.

The Richardson Maturity Model

To understand where HATEOAS fits in REST architecture, we look at the Richardson Maturity Model, which breaks down REST into four levels of compliance:

Level 0 (Swamp of POX): Single URI, single HTTP method (typically POST). Example: SOAP.
Level 1 (Resources): Multiple URIs (endpoints for specific resources) but still using a single HTTP verb or ignoring standard HTTP semantics.
Level 2 (HTTP Verbs): Multiple URIs using proper HTTP methods (GET, POST, PUT, DELETE) and standard HTTP status codes.
Level 3 (Hypermedia Controls): HATEOAS. The API becomes self-documenting by returning hypermedia links that show the client how to proceed.

HATEOAS vs. Standard REST

Feature	Standard REST (Level 2)	HATEOAS REST (Level 3)
URL Resolution	Hardcoded by the client (`/accounts/{id}/withdraw`)	Discovered dynamically from response links
State Decisions	Driven by client-side logic (e.g., check `balance > 0`)	Driven by server-provided links (if link exists, action is valid)
Server Changes	Can easily break clients if URLs change	Completely transparent to clients (they only look for relation keys)
API Coupling	Tight coupling to URL structure	Loose coupling, highly decoupled

HATEOAS Example

Let's assume we request resource details of an article. A standard REST response returns only data:

{
    "id": 42,
    "title": "What is HATEOAS?",
    "content": "HATEOAS stands for..."
}

A HATEOAS-compliant API response includes contextual relationships and links showing how to retrieve them:

{
    "id": 42,
    "title": "What is HATEOAS?",
    "content": "HATEOAS stands for...",
    "_links": {
        "self": { "href": "/articles/42" },
        "author": { "href": "/users/15" },
        "comments": { "href": "/articles/42/comments" },
        "categories": { "href": "/categories/8" }
    }
}

The client does not need to know how the URL for comments or authors is constructed. It simply queries the "comments" link key directly.

The Classic Bank Account Example (from Wikipedia)

To see how HATEOAS controls application state, let's look at the classic bank account scenario.

When a client requests account information for an account with a positive balance:

GET /accounts/12345 HTTP/1.1
Host: bank.example.com
Accept: application/vnd.acme.account+json

The server returns the account data along with all available transitions (deposit, withdraw, transfer, close):

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit",
            "withdraw": "/accounts/12345/withdraw",
            "transfer": "/accounts/12345/transfer",
            "close": "/accounts/12345/close"
        }
    }
}

If the account balance goes negative (-$25.00), the client requests the resource again and receives:

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": -25.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit"
        }
    }
}

Because the account is overdrawn, the withdraw, transfer, and close options are omitted. The client UI can dynamically hide these options simply by checking if the corresponding links are absent, rather than replicating the server's business logic (balance < 0).

What Does HATEOAS Provide?

Decoupled URL Schemes: The server team can change URIs (e.g., from /accounts/... to /api/v2/accounts/...) at any time. As long as the relationship keys (e.g., deposit, withdraw) remain constant, the client will continue working without modification.
Simplified Client Logic: Complex state validation (e.g., eligibility criteria) is kept on the server. The client doesn't need to implement check rules; it simply checks if a link is provided.
Self-Discoverability: Developers consuming the API can explore features interactively by following links, reducing the need for out-of-band documentation.

FAQ

Why isn't HATEOAS widely adopted in public APIs?

While elegant, HATEOAS increases payload sizes because it sends link objects with every response. It also requires client developers to write generic link-traversal logic rather than simply calling static URLs, which many developers find less intuitive.

What are the common standards for implementing HATEOAS?

Unlike standard JSON, HATEOAS requires a hypermedia format. The most popular specifications are:

HAL (Hypertext Application Language): Simple JSON extension with _links and _embedded properties.
Siren: A rich entity-based hypermedia format that supports actions and schemas.
JSON-LD (JSON for Linking Data): Links data contexts globally.

Reference

Wikipedia contributors. "HATEOAS." Wikipedia, The Free Encyclopedia. Wikipedia, The Free Encyclopedia, 18 Mar. 2020. Web. https://en.wikipedia.org/w/index.php?title=HATEOAS&oldid=946088168.

Changelog

2026-06-20: Modernized article structure. Added Richardson Maturity Model explanation, Standard REST vs. HATEOAS comparison matrix, and FAQ regarding format standards and adoption issues.
2022-05-12: Article published.