Which technologies should you use to build hypermedia APIs?
March 13, 2019, 4 min to read
Tutorials are available online to get you started, and they cover most commonly used programming languages.
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 a “W3C (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.
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?