Grading your API’s REST conformance!
The Richardson Maturity Model (RMM) is a way to grade your API according to the constraints of REST. The better your API adheres to these constraints, the higher its score is!
Technically, REST services can be provided over any application layer protocol as long as they conform to certain properties. In practice, basically, everyone uses HTTP Protocol.
Richardson Maturity Model (RMM) is a four-level scale (0–3) that indicates extent of API conformity to the REST framework, where level 3 designates a truly RESTful API.
Level 0 — POX (Plain Old XML)
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 tunnelling mechanism for your own remote interaction mechanism.
These are the most primitive ways of building SOA applications with a single POST method endpoint and using XML to communicate between the client and the server. Examples of these are SOAP and XML-RPC.
Level 1 — Resources
REST’s ‘resources’ are the core pieces of data that your application acts on. These will often correspond to the Models in your application (especially if you’re following the MVC — model, view, controller pattern).
Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
Example here is Instead of going through http://example.org/articles, you actually distinguish between http://example.org/article/1 and http://example.org/article/2
Level 2 — HTTP Verbs
Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
Maturity level 2 is the most popular use case of REST principles, which advocate using different verbs based on the HTTP request methods (GET/PUT/POST/DELETE), while the system can have multiple resources.
Level 3 — Hyper Media Controls
Level 3 is the most mature level of Richardson’s model, which encourages easy discoverability. This level makes it easy for the responses to be self-descriptive.
Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.
Illustrating the RMM levels with an example
Consider the example of creating, querying, and updating employee data.
At Level 0, an employee’s last name would be used to get employee details. Though just a query, HTTP GET is not used instead of HTTP POST. Response body would need to be searched to obtain the employee details. If there’s more than one employee with the same last name, multiple records are returned in proprietary format.
At Level 1, specificity is improved by querying with employee ID rather than with last name. Each employee is uniquely identifiable. This implies that each employee has a unique URI, and therefore is a uniquely addressable resource in REST.
While Level 1 uses only POST, Level 2 improves upon this design by using all the HTTP verbs. Query operations use GET, update operations use PUT and add operations use POST. This also ensures sanctity of employee data. Appropriate error codes are returned at HTTP protocol layer. This implies that we don’t need dig into response body to figure out errors.
At Level 3, response about an employee includes unique hyperlinks to access that employee’s records. GET /employee endpoint returns all the employees. The response is a list of Employees entities. One Employee entity can contain a HATEOAS link to retrieve one particular Employee’s details such as GET /employee/{id} .
