API, REST, JSON, XML, HTTP, URI… What language do you speak?

 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.