Hypermedia APIs

RESTful APIs have enabled the integration of disparate services and build highly dynamic and customisable websites. Developers can also more easily expose certain functionalities for other developers to use and vice versa.

However, as the APIs grow and become more complex, it becomes harder to make sense of how the APIs come together, especially for new developers. 
A new way to design RESTful APIs to overcome this problem is called Hypermedia APIs.

The general idea of Hypermedia APIs is to allow users (of the API) to discover what resources is available through the API itself. From a single end-point, users discover the availability of other end-points through the resources that are returned by the server. I have coded a simple implementation of how such an API might look like here.

There are various formats that have been devised to standardise the design and implementation of hypermedia APIs- HAL, Collection-json, JSON-LD, etc. Fundamentally, most of these are basically JSON or XML-formatted text. They differ in notations and structure of representation. HAL (Hypertext Application Language) is one of the more popular ones and it is quite simple to understand, therefore, I have chosen to implement using HAL.

Introduction to HAL

Hypermedia API usually define a starting end-point from which users can start discovering other resources. In our case, the endpoint is `/api`. Clicking on the ‘start’ button at the top would send a GET request to `/api`.

The website is designed to explore the APIs and shows what has been called under ‘History’, the JSON returned from the GET call under ‘Json’, current links available from the Json under ‘Links’ and a simple page to utilise the Json under ‘Site’.

For HAL, the return object from a GET call is standardised to be a JSON object with a few properties reserved. ‘_links’ is a common reserved property. ‘_links’ represents a collection of resources to which users can call. It is also specified to contain a property ‘self’ which refers to itself. In our case, the additional resource available is ‘authors’ and ‘articles’. The resource itself contains the reference to how to get the resource under ‘href’. Besides the ‘href’ other metadata about the resources, such as size, and description on what the resource represents can also be included as a property of the resource.

The return JSON value for `/authors`

The above screenshot shows what is returned when URI, ‘/authors’, is queried.

As per usual REST-ful APIs, a list of authors is returned. In addition, under, ‘_links’, users can discover additional resources — In our case, the link to page 2 of the list of authors. As we can see, users of this API, can then easily implement pagination without actually knowing the exact number of pages there are. This can be done by adding a ‘next page’ link if ‘next’ exists as a resource under ‘_links’.

The return JSON value for `/authors?page=2`

Similarly, when the 2nd page is called, a ‘prev’ resource gives API users a way to navigate back to the previous state.

In summary, what i have wrote here is a introduction to, what I think, is the basic idea of hypermedia APIs, which is extending the idea of hyperlinks to API calls. It allows API users to more easily discover resources available to them, and allow creators of APIs to communicate the APIs to users. What I have covered here is really basic — just HAL, which is one of the more popular hypermedia API standards, and even just a small subset of HAL, namely, the _links portion. Hope it would be useful to you.

Like what you read? Give Zheng Weihan a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.