Hypermedia APIs — HATEOAS
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated detection is 'no' and tools listed (postman, hal-browser) are manual inspection tools. Hardcoded URL patterns in clients or missing HATEOAS links are only visible through deliberate API response review or runtime testing — no linter or SAST flags this architectural absence.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes adding a _links section, but the common_mistakes reveal that clients must also stop hardcoding URLs and start following links. This requires changing both the API server responses AND all API clients, which is a cross-cutting change spanning multiple components and potentially many consuming services.
Closest to 'strong gravitational pull' (e7). The applies_to covers web and api contexts broadly. Choosing (or not choosing) HATEOAS shapes how every client is written, how URL structures are designed, how documentation is maintained, and how API evolution is handled. Every future endpoint and client interaction is shaped by this architectural decision, but it doesn't quite define the entire system shape (not b9).
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field explicitly states that developers believe 'REST requires HATEOAS' when in fact most production REST APIs are Level 2 and work perfectly well without it. This is a well-documented gotcha — developers invest in full HATEOAS implementation believing it's required for 'proper REST', only to find it adds complexity without proportionate benefit for many use cases.
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