CODEX
Richardson Maturity Model for REST APIs
How RMM can help us build a better API
I’ve been studying REST APIs for some time, and it’s inevitable to reach many articles and recommendations about the Richardson Maturity Model (R.M.M.) developed by Leonard Richardson. It made me think why it’s important, and how we can apply its principles to make an easy-to-use (and understand) API.
After some research and working with (implementing or consuming) REST APIs that complies to the to the highest level of the RMM and others that are far from that, I have had some conclusions I’d like to share in this article.
I like the Richardson Maturity Model definition from wikipedia:
“The RMM can be employed to determine how well a web service architecture adheres to REST principles. It categorizes a Web API into four levels (from 0 to 3) with each higher level corresponding to a more complete adherence to REST design. The next level also contains all the characteristics of the previous one.”
In short, the RMM tells us about the maturity level of a REST API, and the one that complies to the last level is considered “Restful API”.
It’s important to describe the maturity levels of the RMM and its key points.
Level 0
This is the bottom level, that describes a web API with a single URI over HTTP and a single method (usually ‘POST’) accepting all operations supported by the service. So, there is no proper use of HTTP Protocol, which is used as a tunneling mechanism for remote interaction between client and server.
There is no well defined resources, and messaging is done in ‘xml’, ‘json’ or other text formats. Typically SOAP web services falls in this category, and this is called ‘The Swamp of POX’ (plain old XML) approach.
As an example, it can be a service that has an endpoint like /moviesService where you can retrieve information about a movie or its actors, or even insert, update, delete some movie data described in a xml; all by just making a POST request with proper xml payload.
Level 1
At this level, ‘resources’ are introduced. Now the services have many URIs (still all typically using HTTP POST method), and each URI identify one resource, so each resource can be addressed individually now. Now, instead of a single endpoint, it is possible to access individual resources by an specific URI.
We can have now the /moviesService and /actorsService endpoints for example, to request operations over the ‘movies’ and ‘actors’ resources apart.
Level 2
Here the API starts making use of HTTP verbs/methods, as well the HTTP status code. This level leverages the full potential of HTTP as an application layer protocol.
Typically the GET method is used to fetch data from a given resource, while POST, PUT and DELETE methods are used for mutations operations.
So, for a given resource identified by its its URI, its possible to provide full CRUD (Create, Retrieve, Update and Delete) operations.
At this level the HTTP protocol is used to set meaning to requested operations, and the request body will no longer carry operation information. Therefore, the API shows more maturity level than the previous levels.
As an example, we may have a /movie endpoint (URI), where it is possible to read data using GET method, and create/update/delete resources entries using POST/PUT/DELETE verbs. The HTTP 200 response status code can be used to indicate that the operation went OK, while the 400 status code can be used to inform that it was a bad request.
Level 3
This is the last and the most mature of Richardson’s model. This level introduces the Hypermedia representation, also called HATEOAS (acronym of Hypermedia As The Engine Of Application State).
HATEOAS are elements embedded in the response messages of resources which drives the interaction for the API client.
By using HATEOAS, this level encourages easy discoverability and makes it easy for the responses to be self-explanatory. So the service leads consumers through a trail of resources, causing application state transitions as a result.
The API developed at this third level is generally considered as fully RESTful API.
For example, imagine a /movie endpoint (URI) where it was created a new movie resource identified by the id = 10 (creation by POST request). The response can have links to represent current state and further operations, like this:
// json response representation
{
"movie": {
"id": 10,
"name": "Back to the Future",
"releaseYear": 1985
"links": [
link: {
"rel": "self",
"uri": "/movie/10"
},
link: {
"rel": "comments",
"uri": "/movie/10/comments"
}
]
}
} In the example above, we are informed that the URI of the retrieved movie resource is ‘/movie/10’ where we can request operations using http verbs (PUT,GET, etc…); and also it informs that we can request operations about comments resources of this movie at the URI ‘/movie/10/comments’.
Conclusion
When I first saw the “Maturity Model” expression the first thing I thought was: “Oh no, not again!”. In the past, I’ve worked with development processes that tries to comply with some sort of ‘maturity models’ (like “CMMI” for example), and it was not a good experience. Too much bureaucracy and to few shipping code at the time.
But by studying the RMM, I realize that it is kind of simple rules that ensures that the HTTP protocol is used with its full capacities and features.
In a nutshell, a Restful API implementation must be like this:
REST = resource-based URI + full utilization of HTTP specification + Hypermedia(HATEOAS)
Of course there are disadvantages, since I’ve seen some controversy about the Hypermedia representation (HATEOAS). And in ‘json’ request body there is no previous schema validation like ‘xsd’ in ‘xml’.
As a standardization, it saves the client developer time to understand the resources and operations of the API.
In my opinion, following this model avoids the need to build a huge and dense developer portal describing the API. A simple portal listing the ‘resources’, some request/responses examples and swagger/openapi documentation should be enough.
The RMM has few levels, and for the most cases the Level 2 is enough for a good developer experience.
And even if the API is on the bottom levels, there is just few steps to get to the next level, it’s not that difficult!
Therefore, my opinion is that the Richardson Maturity Model can be used as a guide to simplify the process of developing REST APIs, helping developers to design a mature and intuitive Restful API.
