APIadvanced

HATEOAS

A REST constraint where API responses include hypermedia links that guide clients through available state transitions without hardcoded URLs.

Also known as: Hypermedia as the Engine of Application State, Hypermedia-Driven API

Description

HATEOAS (Hypermedia as the Engine of Application State) is the highest maturity level of REST (Richardson Maturity Model Level 3), where API responses embed links to related resources and available actions. Instead of clients constructing URLs based on documentation, they follow links provided in responses -- similar to how a web browser follows hyperlinks. For example, an order response might include links for 'cancel', 'pay', and 'ship' actions, and the available links change based on the order's current state.

The primary benefit of HATEOAS is loose coupling between client and server. When the server controls which links are present, it can evolve URL structures, add new capabilities, or restrict actions based on state and permissions without clients needing code changes. Clients become more resilient because they discover capabilities at runtime rather than having them hardcoded. Common formats for expressing links include HAL (Hypertext Application Language), JSON:API, and JSON-LD/Hydra.

In practice, full HATEOAS adoption is relatively rare in modern APIs because it adds complexity and many API consumers prefer explicit documentation and typed SDKs over runtime link discovery. However, selective use of hypermedia -- such as including pagination links, self links, and state-dependent action links -- provides meaningful benefits without requiring full hypermedia-driven navigation. The key is choosing the right level of hypermedia for the API's consumer base.

Prompt Snippet

Include a _links object in resource responses using HAL format: { "_links": { "self": { "href": "/api/v1/orders/123" }, "cancel": { "href": "/api/v1/orders/123/cancellation", "method": "POST" } } }. Conditionally include action links based on resource state and the authenticated user's permissions -- e.g., only include the 'cancel' link when order.status === 'pending' and the user has the orders:cancel scope. Include pagination links (next, prev, first, last) on all collection responses. Use the HAL media type application/hal+json in the Content-Type header.