Richardson Maturity Model
it is a model (developed by Leonard Richardson) that breaks down the principal elements of a REST approach into three steps: resource, HTTP verbs and hypermedia controls.
Level 0
The base step for a REST API application that uses HTTP as transport layer and nothing else.
Level 1: Resources
In this case instead of calling a generic service we call a more specialised resource service.
For instance, instead of calling “/bookHotel” and passing all information about our booking (hotel, dates, …) we should call ‘/book/hotel/date”
Level 2: HTTP verbs
In the level 2 we use HTTP methods correctly:
GET, to retrieve information (it helps also to manage client caching)
POST and PUT to create/update information, the only real difference is about idempotency:
- PUT is for idempotency. It means that you could call the PUT service multiple time without creating the object multiple time (so theoretically for update)
- POST is not used with idempotent service, it means that if you cal a POST service multiple time the object is created multiple times (so theoretically for insert)
When a new object is created (with PUT or POST) the server has to replay with a 201 and a url indicating where to get this new resource using the GET.
Moreover the response code 409 seems a good choice to indicate that someone else has already updated the resource in an incompatible way. It’s better than a 200 with a message string.
Finally the DELETE should be used to remove objects.
Level 3: Hypermedia controls
In the 3rd level, the server not only sends back to the client the data or object state, but also some other link to some action/service the client can call/use for that object.
For instance, if the client call /book/hotel/date, the response could contain also the link to pay that booking, or the link for the room details, and so on. This allows the client to be more independent from the url or from the services of the server.