HATEOAS — Explained with Examples

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint where API responses include links that guide clients to available actions.

HATEOAS stands for Hypermedia as the Engine of Application State, pronounced “hate-ee-os.” It’s the most advanced and least-adopted constraint of RESTful design.

How HATEOAS Works

In a HATEOAS API, each response includes not just data but also links to related resources and actions the client can take. The client navigates the API by following links rather than hardcoding URLs.

// Without HATEOAS
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

// With HATEOAS
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "links": [
    { "rel": "self", "href": "/api/users/1", "method": "GET" },
    { "rel": "update", "href": "/api/users/1", "method": "PUT" },
    { "rel": "delete", "href": "/api/users/1", "method": "DELETE" },
    { "rel": "orders", "href": "/api/users/1/orders", "method": "GET" },
    { "rel": "friends", "href": "/api/users/1/friends", "method": "GET" }
  ]
}

Real-World Analogy

HATEOAS is like a website with navigation links. A web page doesn’t expect you to know the URL of every other page — it provides menus, buttons, and links to guide you. HATEOAS does the same for APIs: each response tells the client what it can do next, just like a “checkout” button appears after you add items to a cart.

Why HATEOAS Matters

Without HATEOAS, clients hardcode URL patterns like /api/users/1/orders. If the API structure changes, every client breaks. With HATEOAS, clients discover URLs dynamically from the response, making the API more evolvable.

# Without HATEOAS — brittle, hardcoded URLs
user = requests.get('http://api.example.com/users/1').json()
orders = requests.get(f'http://api.example.com/users/{user["id"]}/orders').json()

# With HATEOAS — discoverable via links
user = requests.get('http://api.example.com/users/1').json()
orders_link = next(link['href'] for link in user['links'] if link['rel'] == 'orders')
orders = requests.get(orders_link).json()

Related Terms

REST, CRUD, API Gateway, JSON, HTTP