Recently, I was working on a FastAPI project; I got the idea from the "Real Python" website. While doing my studies on the project, I came across this model. So I thought I’d take a stab at my brainchild and talk about this.
Leonardo Richardson proposed this model. It is used to grade or measure an API by its RESTful maturity.
Leonardo analyzed hundreds of different web services and considered three factors before coming up with this new idea.
Factors
URI: Uniform Resource Identifier
HTTP methods
HATEOAS (Hypermedia)
Categories
Concluding, he divided these elements into 4 categories.
Level 0: The Swamp of POX - Single URI and Single Verb
Level 1: Resources - Multiple URI-based resources and single verbs.
Level 2: HTTP Verbs - Multiple URI-based resources and verbs.
Level 3: Hypermedia Controls - HATEOAS
Take into thought that a level higher is more RESTful than one lower. It is only when an API reaches level 4 that we consider it to be a RESTful API. Let’s delve into them, shall we?
Maturity Levels
Level 0: The Swamp of POX
This level is also known as POX (Plain Old XML). HTTP is only used as a transport protocol for interaction between two systems. It does make use of the full HTTP features like HTTP methods and HTTP cache. To perform operations like get and post, it makes use of a single URI. Most of the time, the only HTTP method used is POST. In essence, this level makes use of SOAP web services in a REST style.
For example, most SOAP Web Services use a single URI to identify an endpoint, and HTTP POST to transfer SOAP-based payloads, effectively ignoring the rest of the HTTP verbs.
To get the data: http://localhost:8080/posts
To post the data: http://localhost:8080/posts
Similarly, XML-RPC-based services send data as Plain Old XML (POX).
Level 1: Resources
Level 1 employs many URIs but makes use of a single verb, generally HTTP POST. It tackles difficulty by disintegrating a single service endpoint into multiple endpoints.
For example:
To get the list of posts: http://localhost:8080/posts
To get a specific post: http://localhost:8080/posts/1
Based on the multiple URIs available, makes this level better than the previous.
Pro tip: There will be no required field in the DB, an empty body is to be sent to the API
Level 2: HTTP Verbs
Level 2 generally hosts numerous URIs and supports several HTTP verbs. At this level, the state of resources can be easily manipulated over the network. i.e., it is now able to perform CRUD operations. For each request, the correct HTTP response code is provided.
To get the list of posts: http://localhost:8080/posts
Response code: 200 OK
This is the most popular use case of REST principles. It is mostly done automatically by different frameworks.
Level 3: Hypermedia Controls
This is the peak level, it is quite the combination of level 2 and HATEOAS (Hypertext As The Engine Of Application State). It helps to describe possible interactions and how to carry them out. The links give client developers a hint as to what may be possible next.
For example, when a request is sent, you get a response, a link and a URI.
CONCLUSION
Be aware that any level you get to still makes your API a RESTful one, this is just to grade maturity.
This is a good way to think about the elements of REST but it’s not a definition of levels of REST. Roy fielding made it clear that this is just a pre-condition of REST.
What I find useful about this RMM is that it helps to understand the basic ideas of RESTful thinking. I see it as a tool to help learn about concepts, not something that should be used as an assessment mechanism.
SUMMARY
• Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
• Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
• Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.
Bonus
Practical project: https://github.com/lennyAiko/RMM-model-API.git
This project was coded using flask, swagger and OpenAPI Specification for REST APIs.