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.

 Version française disponible

REST (Representational State Transfer) is a standard used for developing web services. As the name suggests, a web service makes available a service through web technologies. In other words, the calling system asks a service to the called system via the web which in turn provides an answer. The answer can be negative if the system called does not or cannot fulfill the requested service. This principle of architecture allows systems to communicate with each other. The interest is even more evident for heterogeneous systems using different technologies with compatibility issues (through “direct” communication).

A standardized… standard

With REST, communication is based on web technologies and more precisely on HTTP (Hypertext Transfer Protocol) and URI used by the WorldWide Web. Messages are transmitted in a standardized format. For the integration of responses, the format generally used is JSON (JavaScript Object Notation), more lightweight and less verbose than XML (eXtensible Markup Language) but XML can, of course, be used.

The following is the representation (deliberately simplified) of a train trip:

Using JSON:

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

And the XML equivalent:

<trip>
	<trainNum>123456789</trainNum>
	<departure>
		<station>Brussels-Central</station>
		<time>07:28</time>
	</departure>
	<arrival>
		<station>Liège-Guillemins</station>
		<time>08:25</time>
	</arrival>
</trip>

The data interpretation is very simple as these representation formats are easy to read. Complexity is often related to the data itself. Speaking of traveling in train is not very difficult here.

In today’s technologies, REST web services are very popular for several reasons:

• An obvious simplicity
• The use of HTTP whose qualities are demonstrated. The current version of this protocol is 1.1, dated of 1999 (even before IE6). In computing, we can say that it is very old…
• Systems are increasingly modular, the need for interaction and communication continues to grow.

What about “real life”? Are REST and web services useful?

Yes! Perhaps, you use them every day without paying attention. For example, the fact that you connect to an application using your Facebook account involves some calls to a web service. The third party application asks Facebook whether you authorized it to access your information (email, name, friends list), if so, it provides this information to the application. This exchange allows you to authenticate to the third party application. Such an authentication mechanism/account creation is widely used because:

• Many people use social networks (Twitter, Facebook, Google+)
• Users don’t have to create another account (and therefore provide yet another password).

It is even more important to properly secure your social account because if it’s getting hacked, all your associated accounts become vulnerable. On this topic, I encourage you to read this previous article “Some basic rules to prevent your accounts from getting hacked”.

Technically, what’s happening under the hood?

Calling a web service is done via a standard HTTP request and a standard HTTP response is received. The request can be of type GET (to retrieve data in read-only), POST (to submit data for modification purpose), you can read the complete list of HTTP methods/verbs here. The response will depend on the request and its associated data, this may be the famous 404 response to indicate that the content has not been found, a 403 status because you do not have enough privileges, you can find the complete list of status codes here. Of course, you also have the status 200 to indicate that everything went well (OK status), with a potential response in XML/JSON.

There are some best practices to follow when implementing web services. Examples of what not to do:

• Use a POST request to retrieve data while a GET would have been more appropriate (because the data is not modified)
• Return an empty value (null) with a status 200 when the data has not been found while status 204 or 404 are precisely designed for this.

Also, it is very important that calls are idempotent, i.e. when the same request is sent several times, the response must be consistent. For instance:

• I send a POST request to modify data, I receive a status 200 confirming me that the data has been modified
• If I send the same POST request again, I should now receive a status 304 indicating that the data has not been modified.

Sending the same request several times should never be a problem, you must ensure that the system manages it without side effects.

Let’s talk API

So far we have seen that web services are used to make existing systems communicate with each other, actually there is another main use case. Developers can rely on available web services to develop new features or even build a complete application. In this case, we are talking about API: Application Programming Interface.

To continue with social networks example, let’s take the Twitter API now. Twitter provides a set of REST-based methods to retrieve and manipulate tweets. There are many services available, you can take a look at the complete list of Twitter web services here.

Let’s use a Twitter web service based on a GET. Requests of type GET are easier to test, especially because a click in the browser is enough to create and send the request. The following URL creates a GET to retrieve the list of French tweets concerning this year’s World Cup.

• https://api.twitter.com/1.1/search/tweets.json?q=worldcup2014&lang=fr

Actually, you’ll figure out that the response is not a list of tweets but some error message. You must also add the authentication parameters (ultimately, the click was not enough). In fact, APIs are usually protected and require to be registered before being used. At least, you get the picture and received a JSON response from Twitter (even if it was an access denied…).

We have talked mainly about the Twitter API, but there are thousands of web services and API available. The Google Maps API allows the developer to integrate custom maps. No doubt this openness was one of the ingredients of such success. Indeed, many applications and websites use the Google mapping data to provide new services. Google has a real business plan for companies.

Finally and if you are curious, you can take a look at ProgrammableWeb, a collaborative website that references many API.