REST (Representation State Transfer) is very popular these days. The architectural style is easy to use. You make a GET call to a URL, and get back data in a structured format such as JSON, YAML or XML. Under REST everything is a resource associated with a URL and you work with resources using the standard HTTP verbs such as GET, POST, PUT and DELETE. The simplicity of it all is almost magical.

Yet despite it’s popularity, REST has one underutilized aspect. The use of hypermedia within a REST resource’s data structure provides a concise way to describe additional data associated with a given resource.

Using hypermedia when working REST provides benefits, but it needs to be done with caution. Some understanding about the basics of REST is useful to start with, before we get into the technique itself.

Working with hypermedia links

Look at the JSON in Example 1 below. It’s a response from a fictitious API about rock band, https://api.coolbands/com/bands/11ba72c1-3fa6-422a-ac00-c51e6cfa93a5. The listing shows the data for the not-fictitious band, The Police.

Example 1: A JSON response to a GET request for a band resources

Example 2 describes the same source as Example 1, but does not provide all the details that describe a band member according to the properties firstName, lastName and instruments as is done in members array. Instead, it uses only one property to describe a band member. The member and the value of the member property is a link to another resource, which describes the details of a particular musician. That link is considered a binding to hypermedia.

Example 2: Using hypermedia to get references to the details of a member in a band

This technique, called Hypermedia as the Engine of Application State (HATEOAS), uses hypermedia to reference additional resources from within a particular resource. With HATEOAS, REST resources link to other types of hypermedia that are relevant to the primary resource. Links might describe another REST resource, or the location of media such as audio, video or a JPEG image. A link also can describe related behaviors.

Example 3 below describes a bank account resource. Notice the actions property has a set of subordinate properties that indicate the operations a user can make in terms of the account resource. The operations are defined by URLs that allow the user to deposit, withdraw and transfer money according to the account.

Example 3: A REST resource that supports HATEOAS to define workflow behavior

The HATEOAS approach adds a new dimension to working with REST. You can describe resources according to a variety of media, well beyond text and numbers. For example, the statement property in the banking example above links to a PDF file. Also, under HATEOAS you can also describe behaviors that are relevant to the given resources.

It’s a powerful way to work with REST. But, there are tradeoffs.

Pros and cons of hypermedia and HATEOAS

Associating a resource’s properties to links that bind to hypermedia has two main benefits. First, the physical size of JSON objects that describe a REST resource can be a lot smaller. in Table 1 below, the use of hypermedia on the right requires fewer characters than the raw JSON on the left. The size difference is apparent.

Table 1: A comparison of resource size between raw JSON and HATEOAS

The second benefit of the HATEOAS approach is that you can describe workflow actions relevant to the resource. We illustrated this earlier in the banking example in Example 3.

However, there are two significant drawbacks to putting links to other hypermedia in a REST resource. The first drawback is that using hypermedia incurs more roundtrips on the network to get meaningful data. The second drawback is that you need to have a wider scope of knowledge about the domain in order for the information to be useful.

Go back and take a look at Table 1 above. The information about the musician on the left side of the table is self-descriptive text: the first name and last name of the musician, and the instruments the musician plays just by reading the text. On the other hand, the information on the right side of the table tells you nothing other than where to get the information of interest. Thus, you have to make another trip over the network to get the information you want. Even then, you really don’t know how the information will be structured unless you have prior knowledge.

It gets even trickier if the hypermedia link is associated with a behavior. In the banking example above, you need to know how to POST a deposit beforehand, but those instructions are not available in the resource definition.

The long and the short of it is that in certain cases, you have to know a lot about those particular domains to use HATEOAS effectively. When a REST response is nothing more than properties with text and number values, what you see is what you get. When the property describes a URL, you need to know a whole lot more.

Putting it all together

Adding hypermedia to resource properties takes REST to the next level. It provides a concise way to send resources over the network and enables use of data types beyond text and numbers.

There are tradeoffs for hypermedia and HATEOAS, however. You’ll need to make more roundtrips to get all the information you want from an API. You’ll also need to know a lot about the API beforehand.

Still, adding hypermedia links to your REST resources can provide a richer data experience for your users. It’s a technique worth consideration.