Doing some social REST with HATEOAS

 Version française disponible

The article “API, REST, JSON, XML, HTTP, URI… What language do you speak?” gave some explanations on web services and their related technologies, REST in particular. Let’s assume that you master this topic now, so we can continue our journey and introduce HATEOAS. Although the name sounds a bit barbaric, there is no relation to any character from Lord of the Rings!

We can reuse our example about travelling by train. Note that we are using the JSON format, but you can use XML as well.

{
  "trainNum": 123456789,
  "departure": {"station": "Bruxelles-Central", "time": "07:28"},
  "arrival": {"station": "Liège-Guillemins", "time": "08:25"}
}

This message describes a trip by giving various information such as the train number, departure and arrival stations and the schedule. But there is no information related to the context. Based on the message content, there is no way to know the origin of the data or how to get extra information (on the trip, the train, etc.). This is time for our fellow HATEOAS to help us.

HATEOAS stands for Hypermedia as the Engine of Application State. You should see clearly now! Don’t you? Ok… Let’s put it simply, it is a way to add contextual information to a message. When talking about HATEOAS for REST, we often use the term “constraint” because that extra data must follow a pre-defined and universal format. This standard (like all others) is essential to avoid that everyone creates their own proprietary format, so that they become API specific.

In the case of our trip, it could be interesting to add the coordinates of the previous and next trains. To add such links between the trains and respect the HATEOAS constraint, the message becomes:

{
  "numTrain": 123456789,
  "departure": {"station": "Bruxelles-Central", "time": "07:28"},
  "arrival": {"station": "Liège-Guillemins", "time": "08:23"},
  "_links": {
    "self": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=123456789&departureStation=Bruxelles-Central&departureTime=07:28"
    },
    "nextTrain": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=987654321&departureStation=Bruxelles-Central&departureTime=08:01"
    },
    "previousTrain": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=147258369&departureStation=Bruxelles-Central&departureTime=07:01"
    }
  }
}

The existing data remains unchanged and a block of links has been added. REST web services can be adapted without having too much impact on the existing code, so regression is minimized.

The message has a much more functional sense; from a trip, we can jump to the next or previous one. I have to admit that this example is quite limited, but imagine applying this principle in other contexts.

By providing self-described message, the API is somehow easily discoverable. The response enables to make another request without necessarily knowing in advance all the methods available on the API. HATEOAS greatly improves the readability of your API, but the interest is real when the consumers of the web services are using this added information.

However there is a downside: HATEOAS is relatively young and the specification is not clearly defined. Besides, where can we find it? Other people already asked this question earlier, it seems you can find it here: HAL – Hypertext Application Language specification. There is also this page much more easy to read which also gives you an interesting materials list (in the “Quick links” section), I would definitely recommend it for further reading.

Related posts

API, REST, JSON, XML, HTTP, URI… What language do you speak? Devoxx UK 2018 – Day 2 Maven Site, one step further Flagger – Get Started with Istio and Kubernetes