Hypermedia APIs — HATEOAS

Also Known As

TL;DR

Explanation

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint where responses include links to related resources and available actions. JSON:API and HAL (Hypertext Application Language) are standardised hypermedia formats. A payment response includes links: {self: /payments/42, refund: /payments/42/refund, receipt: /payments/42/receipt}. Benefits: clients are not hardcoded to URL structure, available actions change based on state (no refund link if already refunded), and APIs are self-documenting. In practice: rarely implemented fully; most REST APIs are not truly HATEOAS — they use stable versioned URLs instead.

Common Misconception

Why It Matters

Common Mistakes

• Hardcoding URLs in API clients instead of following links — defeats the purpose of HATEOAS.
• Including links to unavailable actions — the presence of a link implies the action is available.
• Inconsistent link relation names — use standard relations (self, next, prev) where possible.
• HATEOAS as a substitute for documentation — links are machine-readable; humans still need docs.

Code Examples

// Client hardcodes URL structure:
$baseUrl = 'https://api.example.com/v2';
$payment = $client->get($baseUrl . '/payments/' . $id);
$refund  = $client->post($baseUrl . '/payments/' . $id . '/refund');
// Breaks if API moves to /v3/payments or changes URL structure

// HATEOAS response:
// GET /payments/42
{
    "id": 42,
    "amount": 99.99,
    "status": "completed",
    "_links": {
        "self":    {"href": "/payments/42"},
        "refund":  {"href": "/payments/42/refund", "method": "POST"},
        "receipt": {"href": "/payments/42/receipt"}
    }
}
// No refund link when status=refunded — client knows refund unavailable
// Client follows _links.refund — URL can change without breaking client

References

• ↗ https://htmx.org/essays/hateoas/

Tags

Related Terms