Richardson Maturity Model

Richardson Maturity Model provides step by step way to understand the basic ideas behind RESTful thinking. This is more of tool to understand concepts and not something that should be used in some kind of assessment mechanism for your REST api. A model (developed by Leonard Richardson) that breaks down the principal elements of a REST approach into three steps. These introduce resources, http verbs, and hypermedia controls. Each level is a condition for the next, so to qualify for level 3, the only way for a service is to also support levels 1 and 2.

Level 0

The starting point for the model is using HTTP as a transport system for remote interactions, but without using any of the mechanisms of the web. Essentially what you are doing here is using HTTP as a transport mechanism. It will use only one entry point (URI) and one kind of method (in HTTP, this normally is the POST method). Examples of these are SOAP and XML-RPC.

Level 1 - Resources

This is first step towards becoming more RESTful in the Richardson’s Maturity Model. So now rather than making all our requests to a singular service endpoint, we now start talking to individual resources.

When your API can distinguish between different resources, it might be level 1. This level uses multiple URIs, where every URI is the entry point to a specific resource. Instead of going through http://example.com/employees, you actually distinguish between http://example.com/employee/1234 and http://example.com/employee/6789. Still, this level uses only one single HTTP method like POST.

Level 2 - HTTP Verbs

At Level 2, Don't use a single POST method for all, but make use of GET when you are requesting resources, and use the DELETE method when you want to delete a resources. GET is safe and idempotent operation, that is it doesn't make any changes to the state of any resource. This allows to invoke multiple GET safely in any order and still get the same results each time. An important consequence of this is that it allows any participant in the routing of requests to use caching. HTTP includes various measures to support caching, which can be used by all participants in the communication.

The important part of response is the use of an HTTP response code to indicate something has gone wrong. Don't use 200 (OK) code when something went wrong for instance. Rather than using a return code of 200 but including an error response, at level 2 we explicitly use some kind of error response code. It's up to the api designer to decide what codes to use, but there should be a non-2xx response if an error crops up. Level 2 introduces using HTTP verbs and HTTP response codes.

Level 3 - Hypermedia Controls

The final level introduces something that you often hear referred to under the acronym of HATEOAS (Hypertext As The Engine Of Application State). The point of hypermedia controls is that they tell us what we can do next, and the URI of the resource we need to manipulate to do it. One obvious benefit of hypermedia controls is that it allows the server to change its URI scheme without breaking clients. As long as clients look up the linkrels URI then the provider can juggle all URIs except the initial entry points.

A additional benefit is that it helps client developers explore the protocol. The links give client developers a hint as to what may be possible next. Similarly it allows the server team to advertise new capabilities by putting new links in the responses. If the client developers are keeping an eye out for unknown links these links can be a trigger for further exploration.