REST APIs in Depth · Advanced Patterns and Consistency
Hypermedia and Links in Practice
When links in responses help, and pragmatic formats (HAL, JSON:API, RFC 8288).
Full HATEOAS is uncommon, but links are still useful: pagination (next, prev), related resources, and available actions that depend on state (cancel only while an order is pending). Formats: RFC 8288 Link headers, HAL (_links), JSON:API (links, relationships) or simple *_url fields. The pragmatic win: clients ask "is there a cancel link?" instead of duplicating server-side state rules.
Link formats
| Criterion | Link header (RFC 8288) | HAL | JSON:API |
|---|---|---|---|
| Where links live | HTTP headers | _links in body | links/relationships in body |
| Tooling | Universal | Moderate | Rich client libraries |
| Payload overhead | None in body | Small | Larger (strict structure) |
| Best for | Pagination | Pragmatic hypermedia | Fully standardized APIs |
{
"id": "ord_1",
"status": "pending",
"_links": {
"self": {"href": "/orders/ord_1"},
"cancel": {"href": "/orders/ord_1:cancel", "method": "POST"},
"items": {"href": "/orders/ord_1/items"}
}
}
Common pitfalls
- Adding links nobody uses.
- Clients hard-coding URLs anyway.
- Mixing several link formats in one API.
Key points
- Links for pagination, relations and state-dependent actions
- Pick one format
- Use action links to avoid duplicating state rules
Further reading: RFC 8288: Web Linking
Practice questions
What's a practical benefit of including action links like cancel?
Answer
Clients don't need to replicate business rules about when actions are allowed; they show the button only if the server returns the link.
Where are Link headers most commonly used today?
Answer
Pagination (rel="next", rel="prev"), e.g., in GitHub's API.
Open in the app to mark lessons complete, take notes and track your progress.