Introduction
When Meat Loaf sang “Two Out of Three Ain’t Bad”, he could have been talking about the “Richardson Maturity Model”. When I say “two out of three”, I am referencing level two and level three of this model.
The “Richardson Maturity Model”, developed by Leonard Richardson, is a maturity model for REST web services that has multiple levels ranging from level zero to level three. The higher the level, the higher the maturity of your API and thus is the goal of the API developer when designing REST web services.
Richardson determined the API maturity level based on how the service used the following core factors:
- URIs - Uniform Resource Identifiers
- HTTP Methods – the standard CRUD (create, read/retrieve, update, and delete) operations
- HATEOAS - “Hypermedia as the Engine of Application State” or simply put Hypermedia
Level Zero (No Factors)
Level zero does not use the factors above and is considered the most basic. These types of services use one URI, one HTTP method (usually POST), and likely an XML or SOAP-based payload. In such a case, there is a ton of heavy lift using one URI and the payload to communicate between services.
Level One (URIs)
Level one expands on the use of URIs where each resource is given its own URI. This is better but developers are not taking advantage of using more than one HTTP method (again usually POST).
Level Two (URIs plus HTTP Methods)
Level two represents most REST web services and is our minimum recommendation when building your APIs. Here we see services with multiple URIs and use of more than one HTTP method (i.e. POST, GET, PUT, and DELETE). It is critical at this stage for developers to review supporting API specifications (like Swagger) so they know how to properly access and/or modify a resource.
Level Three (URIS, HTTP Methods, and HATEOAS/Hypermedia)
Level three is the highest level of maturity and incorporates all three factors with the introduction of hypermedia.
Hypermedia is any content that contains links to other media types like images, movies, or text. You often find such links in the response content or headers. One great aspect of using hypermedia is allowing services to self-discover by using those links to gain access to other resources. Think of it as me providing you with another web link to click on so you can check out another site. Similarly, when hypermedia is represented in a JSON payload, it is easy for a service to parse the payload and navigate to that additional resource.
Consider this example payload for retrieving information about a product and it returns a link to discover details about the parts:
{
"id": 12345,
"name": "Sink",
"productDesc": "XYZ Sink",
"link": {
"href": "12345/parts",
"rel": "parts",
"type": "GET"
}
}
Your application can now traverse the system to get more information and it did so from the response that you provided. That in a nutshell is “Hypermedia as the Engine of Application State”.
Conclusion
With the “Richardson Maturity Model”, API maturity can be easily understood, and goals can be set for API developers. Our recommendation is to start with level two with plenty of API documentation. You can always work you way up to level three and there are many ways it can be achieved.