Which technologies should you use to build hypermedia APIs?


Which message format should you use to develop hypermedia APIs? HAL? JSON-LD? Mason? Or something else? Which framework is best suited for you, and which JavaScript client? In this article, we compare the various technologies that enable us to build hypermedia APIs.

Just like for APIs that doesn’t provide hypermedia controls, there are three types of tools that can be particularly useful for this kind of work: (i) message formats (e.g.: JSON), (ii) frameworks, and (iii) JavaScript REST clients.

Unlike for RESTful APIs, there are no standards for hypermedia APIs, which is why there aren’t many frameworks and JavaScript clients.

That said, let’s take a look at the solutions available to us in each category. We have found nine formats and seven frameworks which enable us to develop hypermedia APIs, as well as two HTTP JavaScript clients for interactions with a hypermedia API from a front end.

Tutorials are available online to get you started, and they cover most commonly used programming languages.

Message formats

Compared message formats are HAL, Collection+JSON, Siren, Uber, Mason, Json:Api, OData, JSON-LD (which works in combination with Hydra) and Atom.

Mason offers the most comprehensive expressiveness of all of them, and it also has the advantage of being relatively easy to read. However, from what we have observed, HAL is the most commonly used. Its lack of expressive potential has meant we have had to enrich it whenever we have selected it for a project.

Be aware, however, that enriching a format to suit your needs means that the tools that support it will not be able to use this extra vocabulary.

As for JSON-LD, it has the advantage of being linked data-compatible, which can be very helpful. Linked data is described on its (French) Wikipedia page as aW3C (World Wide Web Consortium) initiative that aims to encourage the publication of structured data on the web not via data silos with no connection with one another, but by linking them together to form a comprehensive information network”. We will tell you more about this topic later in the series.

To make it easier for you to choose which technology to use, we have categorized them in the table below. The categories correspond to the different levels in the WS3 maturity model created for Semantic REST APIs. This model adds depth to the very widely used Richardson Maturity Model.


We have found five frameworks which support hypermedia, covering a total of five different languages. One of them – Restfulie – is available in three languages: .NET, Java and Ruby. Because there is a limit to the choice available in every language, we will not look further into this issue here. We hope the table below will help you make your choice.

If none of these frameworks are right for you, you will probably need to develop a library so that you can support the message format of your choice and generate hyperlinks.

If this is the case for you, we recommend that you use the Swagger/OpenAPI vocabulary and structure to send the descriptions of the operations available on resource in the API response. When it comes to generating links, a relatively easy-to-maintain and -conceptualize solution does exist and involves modeling resources using finite-state machines. Once this is done, you would then need to assess the resource to determine which operations are available.

JavaScript REST clients

There are a few JavaScript REST clients out there, including two well documented examples, Traverson and Ketting. Traverson supports Mason, Collection+JSON, Siren and Uber, while Ketting can only support HAL and Json:Api. Both are extendable using custom parsers and are Typescript-compatible.

A still little-used type of API

This type of API is still rarely used and has some rather vociferous detractors, for understandable reasons.

The first of these is simply the lack of standards. Without these, several formats have to be supported, and while some of these might become popular, others might disappear in favor of newcomers. This instability isn’t encouraging.

The second reason is that the most popular tools don’t take advantage of the possibilities these APIs offer. Postman doesn’t know how to deal with it, Angular has no default support, and browser APIs have neither default support nor front end routers or automated testing tools. We need these kinds of tools daily, yet they unfortunately don’t push us towards using hypermedia. We are just crossing our fingers that the maintainers from one of them is reading this article.

Let’s not forget, however, that this type of architecture is a solution to now-pervasive strong client-server coupling, and that despite its immaturity from an API point of view, it still has lots of potential benefits.


In this article, you have explored three examples of technology that might enable you to start developing hypermedia APIs today.

In the next post in our series, we will take a look at machine-interpretable semantics. These offer everything from APIs that are automatically compatible with voice assistants to search engines which find exactly the information you are looking for, as well as reduced documentation and smarter libraries – tempting, right?