Hypermedia in RESTful APIs

In the last few years of my IT experience, I have noticed how every company wanted to build microservices, perhaps by splitting up an already existing monolith.  The advantages of having smaller independent services with single responsibility are widely known, which communicate between each other through RESTful APIs.  However, very few companies - startups and corporations alike - pay attention to an aspect of microservices which, in my opinion, is very important: how to represent data to the external world.

With the classic monoliths responsible for showing web pages, we have always cared about how these pages were connected. Otherwise how can our users navigate the website? Yes, I'm talking about links.

Many developers ignore the fact that even APIs can (and should) provide links, not between pages but between resources. In which case, instead of calling this relation link we would call it hypermedia.

Not to mention that one can completely ignore the possibility to provide - within the response - some useful information, such as the post data template.  These, along with links and additional information, are strictly related to a well defined and known response format: mediatype.

However the most common situation when we make a GET request to a microservice's endpoint, is to get back a response with nested resources, in some  random custom mediatype.
RESTful Web APIs (Richardson/Amundsen/Ruby, 2013) points out that there are very few situations where a new custom mediatype is needed, and even though, it should be well structured, documented, and possibly made it available to the community.


Normally it should be enough to reuse media types. Probably the most common are:

Once you adopt one of this types it will be easy to structure the API response, and instead of nest resources link them. It will be easy to provide also a pagination, a template for the POST and other useful information specific for the resource.

Is quite clear what the benefit are in reusing mediatypes and adopting hypermedia. Perhaps the only disadvantage is that the frontend team, instead of having all the related resources available, will have to make a new ajax call to the relevant endpoint. However, most of time, we only have to display to the user some of the data returned from an endpoint, rather than all the nested resources. Therefore, also in this case, using hypermedia will actually be an advantage.

Antonio Guiliana is a senior PHP developer with over 14 years of experience developing software and leading technical teams.  Antonio is currently working on Maple Syrup Media's main microservice platform.