What Is HATEOAS?

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint where API responses include links describing available next actions, letting cli...

Published November 17, 2026

HATEOAS (Hypermedia As The Engine Of Application State) is a REST constraint where API responses include links telling the client what actions or related resources are available next, so clients follow links instead of hard-coding URLs.

The concept

A response for an order might include links to pay, cancel or view items, and omit 'cancel' if the order has shipped. The server drives the workflow.

It reduces coupling between client and server URL structure, though many practical APIs implement it only partially.

Response with links

GET /orders/7
{ "id": 7, "status": "pending",
"_links": { "self": "/orders/7", "pay": "/orders/7/pay", "cancel": "/orders/7" } }

Practical examples

HAL-style JSON

{
  "id": 7,
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/7" },
    "pay":    { "href": "/orders/7/pay", "method": "POST" }
  }
}

Link header pagination

Link: <https://api.example.com/users?page=3>; rel="next"

Client follows links

const order = await (await fetch('/orders/7')).json()
if (order._links.pay) await fetch(order._links.pay.href, { method: 'POST' })

Common mistakes

  • Adding links nobody uses.
  • Inconsistent link formats.
  • Expecting all REST APIs to support it.

Key takeaways

  • Responses carry next-step links.
  • Server controls available actions.
  • Reduces URL coupling.

FAQ

Is HATEOAS required for REST?

Strictly yes, but few real APIs fully implement it.

Common formats?

HAL, JSON:API and Siren.

More HTTP articles