HATEOAS is, in essence, a value proposition and definition for what an API should do. HATEOAS, or Hypermedia as the Engine of Application State, is a specific constraint upon the REST architecture. For many, however, HATEOAS seems a nit-picky addition to the slew of API design best practices.

Part of this comes from the fact that HATEOAS is surrounded by hyperbole – some definitions seem to imply it’s the solution to all RESTful problems, and others seem to suggest it’s a pointless exercise in enforced design ethos. The truth is that both camps have some valid points, making HATEOAS a tricky thing to consider.

Today, we’ll discuss HATEOS compliance. We’ll look at what HATEOAS actually is, and what it isn’t. Once we’ve dispelled some of the hyperbole, we’ll discuss some formats (HAL, JSON-LD, Siren, Spring, and others) that can help make HATEOAS integration easier and more efficient in your API.

What HATEOAS Is – And What It’s Not

The entire conversation around HATEOAS compliance hinges on one proposition – that HATEOAS has an intrinsic value, and as such, is something that should be integrated as effectively and completely as possible. This proposition hinges on the idea that hypertext is a fundamental skeleton upon which the modern web resides, and as such, it should be the framework upon which web APIs communicate. Each function in HATEOAS should have a related link that allows for further linked resources and actions – as an implementation, it is hypermedia incarnate.

There seems to be some confusion as to the relationship between hypermedia and REST that should be discussed – Roy Fielding himself has commented on this confusion:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. […] In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

Ultimately, HATEOAS is an attempt to integrate hypermedia into RESTful design. There is one other consideration though that should be mentioned – HATEOAS also has strict verbiage restrictions, adhering to the HTTP guidelines. As such, HATEOAS can be summarized as a method for implementing hypermedia while also ensuring that verbiage is respected per the established guidelines.

Arguments Against HATEOAS

Part of what makes compliance somewhat difficult is the fact that there are some valid arguments against HATEOAS in certain applications. Chief of these arguments is the idea that HATEOAS is just a band-aid for non-HTTP verbiage compliance. In other words, if HTTP verbiage strictness did not make headway in the API space, what’s to say that HATEOAS will make any difference?

There’s also a keen argument in the concept that HATEOAS lacks semantic clarity. With everything being defined by relation, some would argue that there’s no such thing as a perfect client that would function as an API while still being able to quickly, automatically, and correctly parse every relation link and their subsequent values.

Tangentially, there is a related argument that HATEOAS has no reverse flow clarity. Because there’s often no clear “a to b” connection, and instead a series of relations, reversing the flow on a call can result in a circular reference in appearance.

Ultimately, the main argument against HATEOAS is that it’s a straight jacket of constraints which seems to offer little in return.

The Value of Hypermedia

While the above arguments are technically valid, they miss a huge point – every single one of those arguments are true for applications that already do not have a need for a Hypermedia system. For a standard API that has only a few, unrelated calls, HATEOAS does not make sense. For a business-to-business API that taps into private systems, discoverability is a non-concern, and as such, HATEOAS does not make sense.

For any system that does need discoverability, however, HATEOAS is a godsend. Hypermedia allows a single URL, once contextualized with appropriate documentation and guidance, to be used as a method for navigating the entire system. It allows for truly complex utilization, because it doesn’t lock understanding behind documentation alone – in theory, and with a purpose-built HATEOAS compliant client, the verbiage in use is standard, expected, and understood, forming a type of lingua franca for developers and users alike.

It should also be considered what non-implementation of a hypermedia system would look like if the need is present. In a system which requires discoverability, without HATEOAS, all discovery would have to be done manually, either through utilization of the documentation or through trial and error. While this could be partially rectified by making the codebase easier to understand and utilize, the burden of understanding should not fall entirely on the client – after all, poorly formed clients and lacking of user understanding is what makes this all an issue to begin with, so expecting them to fix the problem is akin to “kicking the can down the road.”

In other words, HATEOAS should be seen not as a bandaid, but as a type of protocol – the more APIs utilize it and the value it brings to the table, the more strictly clients will have to restrict their understanding of verbiage, and the more clear the relations of data will appear. Sure, certain API design ethos and approaches do not allow for HATEOAS – but where possible, it offers enough positives to outweigh its negatives and deliver value to the end user.

Common HyperMedia Formats and Tools

HATEOAS has been developed upon quite heavily, and as such, there are an ever-increasing cadre of offerings for various formats of hypermedia. While some of these are specifically languages, others are frameworks and tools that can help expand an already established API into the hypermedia space.

JSON-LD

JSON is a very common format for APIs in general, but it has one major weakness that makes adoption of hypermedia a problem – JSON does not have a built-in hyperlink mechanism. Considering that hyperlinks form the backbone of hypermedia, this creates some significant issues in HATEOAS compliance.

JSON-LD is one solution that attempts to fix the problem. Endorsed by the World Wide Web Consortium, JSON-LD is essentially JSON with additional syntax designed specifically for linked resources – hence, “JSON for Linked Documents”. JSON-LD utilizes keywords that add context to existing functions in the API, introducing additional information to the resource in an attempt to add relationships that can be more fully understood and related to.

A huge value proposition for JSON-LD is the fact that it does not fundamentally change the codebase, and as such, can be implemented without affecting the API in any breaking, significant way. JSON-LD is best, then, for JSON APIs that cannot suffer downtime, cannot support a separate development track for conversion to a hypermedia format, and for developers who are weighing the cost of hypermedia with its benefits.

A simple example of how JSON-LD looks:

{
"@context": "https://json-ld.org/contexts/person.jsonld",
"@id": "https://dbpedia.org/resource/John_Lennon",
"name": "John Lennon",
"born": "1940-10-09",
"spouse": "https://dbpedia.org/resource/Cynthia_Lennon"
}

HAL

A visual representation of how a HAL representation is structured.

Designed by Mike Kelly, HAL is another popular format, much loved for its lightweight implementation. HAL utilizes the hypermedia-laden concepts of Resources and Links as a methodology of modeling the relationships between functions within the API, with Links leading to additional Embedded Resources. Embedded Resources offer the fundamental linkage between the current resource state and related content as held by the relationship link – for instance, in a HAL API, a call to the “user” resource might have an Embedded Resource of “friendslist”, detailing all the URLs of the friends related to that singular user URL.

Example of an embedded resource in HAL:

{
  "_links": {
    "self": {
      "href": "https://example.com/api/book/hal-cookbook"
    }
  },
  "_embedded": {
    "author": {
      "_links": {
        "self": {
          "href": "https://author-example.com"
        }
      }, 
      "id": "shahadat",
      "name": "Shahadat Hossain Khan"
    }
  },
  "id": "hal-cookbook",
  "name": "HAL Cookbook"
}

HAL is a popular format because of its lightweight syntax, but it does have one major drawback compared to JSON-LD – it operates as a model of relationships, meaning that your API might have to undergo significant changes in order to reap the benefits of HATEOAS. While there are many tools that make this conversion easier, it’s a hard sell to utilize for long-standing APIs that cannot have downtime and cannot support forked development. That being said, the user experience is good, and developers appreciate the syntax simplicity, so for new projects (and even existent projects with time and effort to spare), HAL is a great option.

SIREN

SIREN functions utilizing the concepts of Entities, Properties, and Links. An Entity is essentially a generic entity that represents a resource. This resource can then have an optional class that further defines the type of resource, forming a type of inline ad-hoc documentation. This definition is given via Properties; key-value pairs that define the resource with additional information and context. From here, SIREN utilizes Links, which function exactly how you would expect, defining a relation and the link itself.

While SIREN functions with a pretty standard set of approaches, one of the biggest things it adds to the conversation is a definition of Actions. Many Hypermedia states don’t actually explain or dictate what actions can be taken on a resource, meaning that once the URI is understood and discovered, it may not be easy to actually utilize. SIREN fixes this by noting the allowed Actions, notating the method, the fields that can be acted upon, the class of actions, and more. Ultimately, this does quite a lot to make HATEOAS systems both discoverable and utilizable, which is a major issue noted by HATEOAS decriers.

ION

ION is a newer hypermedia type that seeks to establish a series of media type names and versions in its codebase, defining the relationship between resources using links and object definitions. Because ION is relatively new, it’s hard to objectively argue the long-term value proposition of the solution.

That being said, ION does a very good job of providing serialized links to related content, and does so in a very clear manner. It suffers from the same drawbacks of having a specific approach and syntax, however, which can make utilization more difficult for already-developed codebases.

JSON API

JSON API is a strong contender for establishing linked content due to its reliance on forming a graph of data. While there have been many implementations of so-called “graphed data,” perhaps the most significant of which being GraphQL, JSON API utilizes the “Compound Documents” approach to include additional resources with the requested resource to the requester. Clients can then reduce the amount of data being transmitted using Sparse Fieldsets to limit the data only to that which is actually requested, thereby receiving linked content while also ensuring the management of the response size.

It should be noted as well that, in addition to the hypermedia implications of JSON API, the solution offers cacheability and pagination that other graphing solutions like GraphQL do not. In this way, JSON API offers a wide range of benefits and functions that should be considered. Again, like other options on this list, this requires significant time for implementation and a specific syntax – and for many decriers, this may be a significant drawback.

Spring by Pivotal

There are a variety of methods that developers can utilize in order to build HATEOAS compliant systems. While these vary from application to application, they can be separated into one of a few categories. One such category is the concept of complying with HATEOAS by implementing a framework from the ground up. By tackling the problem at the very base of development, many of the late-stage costs of integration and conversion can be entirely avoided – in other words, it is cheaper in terms of time and effort to build a HATEOAS compliant system from the ground up than it is to revise after the fact.

Spring approaches these problems in HATEOAS by providing such a framework through which to construct your API. Pivotal utilizes a representation class and a _links property to define related data content for specified resources. All of this interaction is handled by specific controllers, which route the user input and model interactions based upon the appropriate controller and application logic for the given subset of interactions.

Ripozo

Another tool would be Ripozo. While not necessarily a framework in the sense of Spring, Ripozo acts almost as a wrapper, defining inter-resource links using a class/definition pair. A class such as “Resource” would have values including “id,” “type,” “member,” and so forth. These classes can then be used to form a network of linked resources that results in an API that is truly self-describing, allowing for self-discovery.

One of the main selling points of Ripozo is that it has a wide breadth of options for frameworks, languages, and implementations. In addition to this, there’s direct framework integrations with Flash and Django, as well as two direct database integrations with SQLAlchemy and Cassandra.

Conclusion

While there are points to be made both for and against HATEOAS, the underlying concept of hypermedia is simply too valuable to ignore. While HATEOAS may not be a silver bullet solution, in many REST-oriented cases, it offers a value proposition that makes adopting it more beneficial than the sum of its drawbacks.

That being said, implementation is of course entirely contextual to the situation at hand – for APIs that do not wish to adopt HATEOAS or hypermedia, the lack of adoption can be seen as much a feature as a drawback. In those situations, especially in the case of failure to implement hypermedia at all, these APIs should not be considered or called RESTful per the creator’s own definitions.