What is HATEOAS and how it works

Short answer

HATEOAS, or Hypermedia as the Engine of Application State, embeds links within API responses so clients can navigate resources dynamically without hardcoding URLs.

How it works

A HATEOAS response includes a links array or object containing relations such as self, next, prev, and related. Clients follow these links to perform state transitions rather than constructing URLs from documentation. This decouples the client from server URL structures, allowing the server to evolve its routing without breaking consumers. The approach aligns with the highest level of the Richardson Maturity Model for REST.

Example

A GET /orders/123 response might include links to payment, cancel, and invoice resources. If the order is already paid, the cancel link is omitted, guiding the client to valid next steps based on current state.

Why it matters

HATEOAS reduces client breakage when APIs change, improves discoverability, and enables generic API clients that adapt to any compliant service.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.

Additional context

Applying these principles consistently across projects leads to more maintainable systems, clearer team communication, and better outcomes for end users. Regular review and refinement of practices ensure continuous improvement.