Hypermedia, or more specifically the concept of Hypermedia as the Engine of Application State (HATEOAS), is a principle of REST (REpresentational State Transfer) that has been outright ignored; neglected at best in modern API implementations. This essay delves into the hows and the whys this happened.
Hypermedia refers to content that contains links to other content, allowing for navigation between different resources. When referring to REST, its implementation means the server responses should contain the links that guide the client on what actions can be taken next. For example, think of an e-commerce website where the user hasn’t yet added any items to cart. It wouldn’t make much sense to see a resource for checking out without the user first adding items to cart. With correct Hypermedia implementation, the server can respond with the dynamic content omitting the checkout resource until something has first been added. No prior knowledge of the API is required by the client.
HATEOAS stands for Hypermedia As The Engine Of Application State and is a specific application of Hypermedia in RESTful APIs. It dictates that a client should interact with the RESTful service entirely through the Hypermedia provided dynamically by the application servers.
The client does not need to know the structure of the service beyond the initial entry point. All actions and available resources to the application are discovered through the links provided in responses.
For a more in-depth understanding of Hypermedia and HATEOAS, a list of resources will be put together at the end of this essay.
Many RESTful APIs are designed with static endpoints that clients are expected to know ahead of time. Modern web developers know this concept all too well. These APIs often require clients to hardcode knowledge of all the endpoints, their parameters, and responses.
At the time of writing this essay, I had just completed work on an application for a client that required several API calls to retrieve JSON data. I had to have prior knowledge of the API, the data types returned, and hardcoded of all interactive features in order to have a useable application.
Implementation of a HATEOAS-compliant API would eliminate the need for clients to know the full set of endpoints beforehand. They would discover available actions by following links returned by the server (enter Hypermedia). However, this is not the behavior of contemporary REST APIs. Without these dynamic links, the client and the server become tightly coupled; which completely negates the key benefits of REST. By design, REST should be a loosely-coupled system.
In a true HATEOAS-compliant API, clients would not need to know the full set of endpoints beforehand. Instead, they would discover available actions by following links provided in the responses (enter Hypermedia). However, in practice, most APIs do not provide these dynamic links, leading to a tight coupling between the client and the server. This negates of the key benefits of REST. -Which should be a loosely coupled system in theory.
API responses typically return raw data without any links or additional information on what the client can, or rather should, do next. For example, a GET request to /api/v1/users/1 returns a JSON object with user details but no links to related resources like their shopping cart or payment settings.
With Hypermedia correctly implemented, the response would include links like rel="self", rel="update", rel="delete" that describe how to navigate or interact with the returned resource. This is missing in contemporary REST APIs.
The majority of REST APIs are built around basic CRUD operations. These APIs are often designed as simple mappings of database tables to HTTP endpoints, without considering the dynamic nature of resources or actions that HATEOAS promotes. HATEOAS is about more than just exposing CRUD operations. It’s about representing the state and actions available on a resource dynamically. Most APIs won’t provide this level of interaction or navigation within their responses.
Popular API frameworks and tools often prioritize simpllicity and speed of development over strict adherence to REST, including HATEOAS. These tools make it easy to generate CRUD endpoints and responses, but won’t provide support for hypermedia links or guiding state transitions. Developers using these tools might find it cumbersome to implement HATEOAS properly, leading to its omission completely.
As a result of this, Hypermedia links and dynamic state transitions won’t be included in API responses.
Clients are often designed with assumptions about the API’s structure and endpoints which lead to brittle systems tha could break if/when the API evolves or changes. The client will undergo refactoring whenever changes are made to the API to ensure functionality.
This goes against the idea of clients being able to interact with the API dynamically through Hypermedia.
Instead of using Hypermedia to discover available actions, the clients are over-specified, with knowledge of every endpoint and required data. This presents incredible maintenance overhead and less flexibility in the API.
A careful and thought-out process is required to truly implement HATEOAS effectively as it requires more work to include relevant Hypermedia links in every response. Developers might view this as unnecessary complexity, especially if their use case seems to function well without it. In a world where time is money, teams would much rather have a less conventional system if it means paying less to implement it. As applications evolved, the neglect of Hypermedia and HATEOAS meant quicker development turnaround despite a lack of efficiency or smaller bundle sizes.
In other words, it’s better to carry 4GB of dependencies, require a complex working knowledge of the server endpoints, and the information returned than it is to spend time carefully planning and designing the API that would otherwise save the client extra resources not required with HATEOAS. This is the view of the modern development industry.
Frontend frameworks like React, Angular, Vue, and mobile applications are often built with a clean understanding of the API structure, making Hypermedia less relevant to them. These clients typically rely on a known set of endpoints, reducing the perceived need for Hypermedia-driven navigation.
When it comes to microservices artchitecture, API gateways are often used to aggregate and expose multiple services as a single API. These gateways may provide a fixed API surface that clients interact with, further discouraging the use of Hypermedia.
HATEOAS is foundational in Roy Fielding’s original REST vision, but it was never widely adopted in the industry. Without the broad industry standards and practices that might have enforced HATEOAS, it remains an underutilized feature in REST APIs.
The neglect of Hypermedia and HATEOAS in modern REST APIs represents a significant departure from the original vision of REST. While modern APIs have become highly efficient and scalable, the omission of Hypermedia has led to tighter coupling between clients and servers, reduced flexibility, and more brittle systems overall.
The reasons have hopefully been made clear and concise.
Fielding, R. T. (2000). Architectural styles and the design of network-based software architectures (Doctoral dissertation, University of California, Irvine). UCI’s Donald Bren School of Information & Computer Sciences. Chapter 5. Retrieved from https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Gross, C. (n.d.). HATEOAS. htmx.org. Retrieved from https://htmx.org/essays/hateoas/
Gross, C. (2021). Hypermedia APIs vs Data APIs. htmx.org. Retrieved from https://htmx.org/essays/hypermedia-apis-vs-data-apis/
Severance, C. (2015). Roy T. Fielding: Understanding the REST style. Computer, 48(6), 7-9. https://doi.org/10.1109/MC.2015.170
© 2025 Aron Sweet
Built with Astro & Tailwindcss. Hosted on Netfliy.