Saturday, June 13, 2015

The RESTful API



About 2 years ago I was in multiple meetings where the term RESTful API (Application Programming Interface) kept coming up.

Nobody bothered to precisely define it and I erroneously thought it was just a /fancy/ word for API.  In other words synonymous for API.

So this morning I came across the definition of REST

Representational State Transfer  (REST)

Here is the IBM Redbook which discusses the API for IBM's Enterprise DS8870 Storage System

Exploring the DS8870 RESTful API Implementation

And so here is a good summary from Stackoverflow


REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The key constraint is that the server and client must both agree on the media used, which in the case of the web is HTML.
An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. An HTML form is an example of this: The server specifies the location of the resource, and the required fields. The browser doesn't know in advance where to submit the information, and it doesn't know in advance what information to submit. Both forms of information are entirely supplied by the server. (This principle is called HATEOAS.)
So, how does this apply to HTTP, and how can it be implemented in practise? HTTP is oriented around verbs and resources. The two verbs in mainstream usage are GET and POST, which I think everyone will recognise. However, the HTTP standard defines several others such as PUT and DELETE. These verbs are then applied to resources, according to the instructions provided by the server.

So what would I recommend?

- Obviously the overriding principle is, when you realise there is a gap in your knowledge, head to the Internet for a catchup
- Don't be too proud to admit your previous knowledge gap!
- Read the StackOverflow article first
- Read IBM Developerworks on REST
- Then take a look at the IBM redbook, lots of examples.