How should I build a RESTful API? /Act II. - Is your API mature enough?/

After Act I. we know the basics of the REST architectural style. Before start the development process we should take a look at an important Model, which is a kinda de-facto to measure how RESTful is an API.

That is the Richardson Maturity Model. This model also helps us to see a big picture of how should look our API in a way of RESTful.

Let's take a look at Martin Fowler's explanation.

REST has a Uniform Interface, which does not have to be the HTTP, but we're web developers so we'll use HTTP as our Uniform Interface!


Level 0 - The Swamp of POX (Plain Old Xml):
At Level 0 we use HTTP as a tunnel to Remote Interactions. We use only one entry point (URI) and one kind of HTTP method (e.g. POST). Examples: SOAP, XML-RPC, JSON-RPC


Level 1 - Resources:
Now we use multiple entry points (URIs), which are unique identifiers to retrieve resources. This level still uses only one HTTP method. Examples: http://api.example.com/cars, http://api.example.com/cars/1, http://api.example.com/cars/2


Level 2 - HTTP Verbs:
At Level 2 we proudly introduce multiple HTTP verbs. Use GET for read a resource, DELETE to delete it and so on (anyway REST != CRUD).
Another important principle is that the usage of the proper HTTP response codes to indicate status. Do not rely always the response 200 (OK), we should be more sophisticated and should toss our almost RESTful API toward a semantic web.
Examples: After a resource creation the proper HTTP response code is the 201 (Created)


Level 3 - Hypermedia Controls:
Hypertext As The Engine Of Application State (HATEOAS). This is the highest level. Without reaching this level our API is not RESTful!
Hypermedia controls are URIs attached to a given resource. These controls tell us what can we able to do next with the resource (e.g. add a related resource to it). One of the main benefit is that it allows us to change the URI schemes without breaking the clients. Another one is that it helps to explore the API.
Examples: go to Martin Fowler's explanation


References:
http://nirmata.com/2013/10/rest-apis-part-1/
http://martinfowler.com/articles/richardsonMaturityModel.html