In our What is REST? article we focused on a few of the important constraints of REST that are relevant to the SRP HTTP Framework. When discussing the Uniform Interface constraint, we provided an introduction to the concept of Hypermedia As The Engine Of Application State (or HATEOAS for short). In our summary of the concept of HATEOAS, we emphasized its importance but suggested the reader visit this present page to understand why HATEOAS is important.
To be fair, there are plenty of people who appreciate REST in some respects, but ultimately do not see the significance or value of HATEOAS. This approach to RESTful APIs is often referred to as pragmatic REST. RESTful APIs that emphasize HATEOAS is sometimes referred to as purist REST (perhaps derisively by non-purist developers). This article from Ben Morris represents a well reasoned argument against the necessity of HATEOAS, although we suggest that in some ways it indirectly advocates the need to engage HATEOAS. Our intent is not to debate the subject or pick apart any arguments against HATEOAS. Rather, we prefer to just outline our case for HATEOAS so each developer can make up their own mind. The important part is for a developer to decide early on whether or not HATEOAS will be a normal part of the API. This is why the SRP HTTP Framework does not enforce HATEOAS implementation but it does provide tools to implement HATEOAS relatively easy.
It is important to define our terms and demonstrate our concepts in order to illustrate the importance of HATEOAS. We'll do this by looking at the major items in HATEOAS: Hypermedia, Engine, and Application State.
Hypermedia
Hypermedia refers to content in a resource that is itself, or somehow it contains, a URI link to another resource. The most common type of hypermedia is we experience is hypertext. It is arguably the most significant reason why the web so easy to navigate and explore. Consider any website that you load into a browser. How does one discover and explore additional content that is available? We all know the answer: through the URI links available on the page. In HTML, we usually encounter these as text, or images, that are created using the anchor tag. Visitors do not require a road map nor do they need instructions on how to manually enter new URIs in order to access other content. The embedded hypermedia provides a visitor everything needed to continue. This addresses one important benefit of hypermedia: self-documenting systems. That is, assuming that the links are well labelled and clearly identified on the page, they serve as self-documenting elements that the users can easily understand.
Another benefit of hypermedia, although one that might not be obvious to the typical visitor, is that a website could change the URI of a resource without advertising this to the user. All that is important is that when the user visits a landing page, the URIs referenced by the hyperlinks is current. Therefore, as long as the site continues to publish the correct URI to a resource, the user will always be able to navigate to the correct location. This introduces another import benefit of hypermedia: client/server independence. That is, web servers should be allowed to change as needed and not worry about breaking any client functionality (i.e., the web browser client) because the server is always providing the client with current URIs.
These two benefits can also apply to web APIs. If our resource objects contain hypermedia, then our APIs become self-documenting. If the system that communicates with our API understands that it will receive hypermedia then we will achieve client/server independence. Our APIs, then, can evolve much easier (as well as the client relying on our APIs). This Martin Nally article doesn't discuss REST or HATEOAS directly, but it does provide a very thoughtful and compelling reason for using hypermedia (aka links) in APIs.
