REST zealots would argue that if your API does not support hypermedia then you're not using REST. They do have a point if you use Fielding's (rarely read) thesis as the sole definition of what constitutes a “RESTful” service.

Fielding was very explicit about the importance of hypermedia to REST in a more accessible blog post:

"A REST API should be entered with no prior knowledge beyond the initial URI… From that point on, all application state transitions must be driven by client selection of server-provided choice… "

Clearly, if you're not using hypermedia to drive application state then you're not really RESTful in terms of the architectural style that Fielding described.

Does Hypermedia matter?

Using HATEOAS (Hypermedia as the engine of application state) allows an API to define the control logic available to clients. It gives rise to a discoverable API where clients follow links embedded in resources rather than directly manipulating URLs. This reduces the scope for breaking changes by decoupling clients from the URL structure so any changes won't break client integrations.

Given the potential benefits it's surprising how few "RESTful" APIs implement HATEOAS. There are many examples of resource-orientated HTTP APIs that are not RESTful in the strict Fielding sense. For example, neither the Twitter or Facebook APIs use hypermedia. This may be the “spirit of the law” versus the “letter of the law” as a pragmatic approach seems to be prevailing.

This does not mean that these pragmatic REST APIs are somehow immature. The Richardson maturity model is often quoted in this context, as it implies a progression from resources to HATEOAS in achieving the “glory that is REST”. This was developed more as a means of explaining the concepts behind REST rather than suggesting a practical route for progression.

HATEOAS may be the purists' choice, but it does come with a certain amount of baggage. It makes an API more complex to implement while tending to bloat the response. It can give rise to a more “chatty” style of integration as clients navigate through links rather than jumping straight in to the resources they need.

More importantly, in many cases it fails to deliver on its stated benefits.

Clients never use it

Perhaps my main reservation with HATEOAS is that is elective in that many clients will not leverage it. If you are exposing a public API then you cannot enforce a client to use it in the “correct” way. In most cases a developer will read the documentation and access the end points directly rather than following the options presented in responses.

In most cases, the stated benefit of separating implementations from any knowledge of endpoint names is not realised. If you change your endpoints then you won't have obedient clients following links to the new locations – they are more likely to just break.

Which format?

Another challenge with HATEOAS is in the lack of any consensus over format. Once you decide to adopt hypermedia you have to decide how you will present the links, formats and documentation that make your API discoverable, i.e. the hypermedia type.

The problem is that everybody seems to do this differently and there is no de facto standard. Hal is simple and easy to understand, JSON-LD is easier to apply to existing APIs, Siren represents data in terms of generic classes and supports actions, Collection-JSON excels at dealing with lists of data while JSON API is a recent format that has gained some traction due to its simplicity and versatility.

This diversity of implementations demonstrates how difficult HATEOAS can be to nail down. Many organisations have even been tempted to roll their own – the PayPal API being one example of a custom hypermedia scheme.

Given this diversity of implementation, there's no prospect of being able to create a generic REST client, like a web browser for data. Each API presents a very different format that requires a different integration.

Data is not media

No matter what hypermedia type you are dealing with, it remains very difficult to communicate the meaning of data through HATEOAS. There will be times when the client needs to understand the semantic meaning of data before it can carry out any operations on it. REST does not really have an answer here as it treats all data as generic media.

Given this need for semantic meaning you can't create a generic REST client for data that traverses hypermedia. Ultimately, you need to supplement the information provided by hypermedia with documentation to understand the context of the data. In this sense, the definition of REST is overly-academic and based on a false assumption that data can be handled in the same as media. The idea of a self-discovering API may be attractive in theory, but this is difficult to leverage in practise.

Are stateless resources enough?

Given the obstacles to getting any genuine benefit from HATEOAS, is it easy to see why a more pragmatic style of REST API has become so popular.

Besides, many of the more tangible and realistic benefits of REST are derived from designing an API in terms of stateless resources. This approach makes an API easier to scale as you don't need to worry about maintaining state around a delivery infrastructure. It also tends to give rise to APIs that are intuitive for web and mobile developers who are already familiar with the style of interface.

The more accessible and scalable aspects of REST APIs may be improved by the control structure provided by HATEOAS, but they are not dependent on it.

Filed under API design, Integration, REST and Distributed Applications.