Richardson Maturity Model
- Summary
-
Discussion
- What are the different levels in the Richardson Maturity Model?
- Could you illustrate the RMM levels with an example?
- What are the characteristics of RMM Level 0?
- What are the characteristics of RMM Level 1?
- What are the characteristics of RMM Level 2?
- What are the characteristics of RMM Level 3?
- What sort of applications can still be designed with Level 0 or Level 1 APIs?
- When does it become necessary to have APIs designed at Level 2 or Level 3?
- What are the other models used to judge the design standards of remote application interfaces?
- Milestones
- Sample Code
- References
- Further Reading
- Article Stats
- Cite As
Consider remote web servers as huge repositories of data. Client applications can access them via APIs. It could be public data such as weather forecasts, stock prices, or sports updates. Data could be private such as company-specific business information that's accessible to employees, vendors or partners.
REST (REpresentational State Transfer) is a popular architectural style for designing web services to fetch or alter remote data. APIs conforming to the REST framework are considered more mature because they offer ease, flexibility and interoperability. Richardson Maturity Model (RMM) is a four-level scale that indicates extent of API conformity to the REST framework.
The maturity of a service is based on three factors in this model: URI, HTTP Methods and HATEOAS (Hypermedia). If a service employs these technologies, it’s considered more mature. This model covers only API architectural style, not data modeling or other design factors.
Discussion
-
What are the different levels in the Richardson Maturity Model? RMM has four levels of maturity, from the lowest to highest:
- Level-0: Swamp of POX: Least conforming to REST architecture style. Usually exposes just one URI for the entire application. Uses HTTP POST for all actions, even for data fetch. SOAP or XML-RPC-based applications come under this level. POX stands for Plain Old XML.
- Level-1: Resource-Based Address/URI: These services employ multiple URIs, unlike in Level 0. However, they use only HTTP POST for all operations. Every resource is identifiable by its own unique URI, including nested resources. This resource-based addressing can be considered the starting point for APIs being RESTful.
- Level-2: HTTP Verbs: APIs at this level fully utilize all HTTP commands or verbs such as GET, POST, PUT, and DELETE. The request body doesn’t carry the operation information at this level. The return codes are also properly used so that clients can check for errors.
- Level-3: HyperMedia/HATEOAS: Most mature level that uses HATEOAS (Hypertext As The Engine Of Application State). It's also known as HyperMedia, which basically consists of resource links and forms. Establishing connections between resources becomes easy as they don’t require human intervention and aids client-driven automation.
-
Could you illustrate the RMM levels with an example? Consider the example of creating, querying, and updating employee data, which is included in the Sample Code section.
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.
-
What are the characteristics of RMM Level 0? API at this level usually consists of functions passing the server object and the name of the interface to the server object. This is sent to the server in XML format using the HTTP post method. The server analyses the request and sends the result to the client, also in XML. If the operation fails, some sort of error message will be in the reply body.
At Level 0, you can do an actual object transfer between the client and server, not just its representation state (as in REST). Object data can be in standard formats (JSON, YAML, etc.) or in custom formats. If it’s SOAP, the specifications are in an accompanying WSDL file.
HTTP is used in a very primitive manner, just as a tunnelling mechanism for the client’s own remote operations. For that matter, other application layer protocols such as FTP or SMTP can also be used.
-
What are the characteristics of RMM Level 1? Level 1 employs several URIs, each of which leads to a specific resource and acts as an entry point to the server side. This aspect is common with Levels 2 and 3.
Requests are delivered to the specific resource in question, rather than simply exchanging data between each individual service endpoint. While this seems like a small difference, in terms of function it’s a critical change. The identity of specific objects is established and invoked. Only arguments related to its function and form are passed to each object/resource.
From this level onwards, it is always HTTP as the application layer protocol. The key non-conformity to REST in this level is disregarding the semantics of HTTP. Only HTTP POST is used for all CRUD (Create, Read, Update, Delete) operations. The return status and data retrieved are all in the body of the HTTP response.
-
What are the characteristics of RMM Level 2? The emphasis in this level is on the correct usage of the various HTTP verbs, especially the use of GET and POST commands. By restricting all fetch operations to GET, an application can guarantee safety and sanctity of the data on the server side. Caching of data at client side for quicker access becomes possible too.
The model calls this level HTTP Verbs. It implies that only HTTP can be used. Actually, REST architectural pattern doesn't mandate the use of HTTP. It's entirely protocol neutral.
At the server side, the 200 series of HTTP response codes should be used properly to indicate success, and the 400 series to represent different types of error.
Taken together, levels 1 and 2 clarify at a high level (such as in server logs) what resources are being accessed, for what purpose, and what happened.
The non-conformity here is quite subtle. The API at this level lacks the transparency for the client to navigate the application state without some external knowledge, generally present in supplied documentation.
-
What are the characteristics of RMM Level 3? In order to ensure complete conformance to RESTful architecture, the final hurdle is to provide smooth navigation for the client throughout the application. This is supported through Hypermedia controls.
The HTTP responses include one or more logical links for the resources that the API accesses. That way, the client doesn’t have to rely on external documentation to interpret the content. Because the responses are self-explanatory, it encourages easy discoverability. This is done using HATEOAS (Hypertext as the Engine of Application State), which forms a dynamic interface between the server and client.
One obvious benefit is that it allows the server to change its URI scheme without breaking clients. As long as the client-facing URI is maintained intact, the server can juggle around its resources and contents internally without impacting the client. Service updates in the application become seamless without service disruption.
It also allows the server team to inform the client of new features by putting new links in the responses that the client can discover.
-
What sort of applications can still be designed with Level 0 or Level 1 APIs? Plenty of online services belong to RMM Level 0 or 1 such as Google Search Service (now deprecated) and Flash-based websites. However, these are slowly being phased out.
If you are designing a monolithic service that performs only one major function, then probably a Level 0 API would suffice as there is no need for multiple URIs. Level 0 is adequate for a service of short-term purpose that's not meant to be extended or upgraded. Think of an exam result declaration website as an example. Its use is restricted to a few days when the results are out. After that, it would just become inactive and irrelevant. There is just one function that the web service performs: it returns an individual student’s pass/fail state. If a few resources are to be accessed, then Level 1 can be employed.
In cases where HTTP is not desired as the transport mechanism, then Level 0 APIs written using SOAP can work even with alternatives like FTP or SMTP.
-
When does it become necessary to have APIs designed at Level 2 or Level 3? Web products and solutions are increasingly being deployed using the SaaS distribution model. To support this, design and manufacturing models are also service-oriented (SOA). They are exposed as microservices, a loosely coupled collection of services.
Popular cloud-based subscriptions such as mobile services, streaming web content, office automation products are all deployed in this fashion. Such services are essentially designed with APIs conforming to the Levels 2 and 3 of the model.
Applications choose Level 2 or 3 due to some additional factors – (1) Need to work even with limited bandwidth and computing resources (2) Rely on caching for greater performance (3) Stateless operations
Lower level APIs like SOAP can be compared to an envelope. It has content inside, address written outside. Content is obscured from public view. However, higher levels that conform to REST are like a postcard. Entire content is directly visible. Though this aspect brings a lot of transparency and discoverability, there is a security threat perception associated with the data. Applications take care of this aspect using security features such as in the Spring framework.
-
What are the other models used to judge the design standards of remote application interfaces? Richardson Maturity Model classifies applications with varying levels of API maturity based on conformance to REST framework.
There is another model called the Amundsen Maturity Model, which classifies APIs based on their data model abstraction. At higher levels of this model, the API is more decoupled from the internal models or implementation details.
Milestones
1998
2000
Rodríguez et al. publish results of a study on HTTP traffic from an Italian mobile internet provider's network. They note most APIs conform to RMM Level 2, implying a focus on providing CRUD access to individual resources. Even when some APIs are at higher levels of maturity, there's wide variation in the adoption of best practices. For example, use of trailing forward slash in URI is not recommended. Use of lowercase and hyphens (rather than underscores) in URI is recommended.
Sample Code
References
- Adobe. 2018. "Granite UI: The Hypermedia-driven UI" Adobe Systems Incorporated. Accessed 2020-02-10.
- Boyd, Mark. 2015. "How The Guardian is Approaching Hypermedia Based API Infrastructure", April 27. Accessed 2020-02-10.
- Cetinkaya, Halil Burak. 2014. "REST & RESTful Web Services." LinkedIn Slideshare, May 25. Accessed 2020-02-02.
- Chapman, Paul. 2015. "Microservices with Spring", July 14. Accessed 2020-02-10.
- Fielding, Thomas Roy. 2019. "Richardson Maturity Model." RESTfulAPI.net. Accessed 2020-02-02.
- Fowler, Martin. 2010. "Richardson Maturity Model." ThoughtWorks, March 18. Accessed 2020-02-04.
- Guru99. 2020. "SOAP Vs. REST: Difference between Web API Services." Guru99. Accessed 2020-02-02.
- Hoffman, Jay. 2017. "SOAP And REST At Odds" The History of the Web, June 26. Accessed 2020-02-04.
- Kumar, Rahul. 2017. "Know how RESTful your API is: An Overview of the Richardson Maturity Model." RedHat Inc, September 13. Accessed 2020-02-02.
- Levin, Guy. 2018. "4 Maturity Levels of REST API Design", 25 November. Accessed 2020-02-10.
- Lewis, James, and Martin Fowler. 2014. "Microservices." ThoughtWorks, March 25. Accessed 2020-02-10.
- Lithmee. 2018. "What is the Difference Between RESTful and RESTless Web Service", November 27. Accessed 2020-02-10.
- Richardson, Leonard. 2008. "Act Three: The Maturity Heuristic." Crummy. Updated 2019-01-16. Accessed 2020-02-02.
- Rodríguez, C, Marcos Baez, Florian Daniel, Fabio Casati, Juan Carlos Trabucco, Luigi Canali, and Gianraffaele Percannella. 2016. "REST APIs: A Large-Scale Analysis of Compliance with Principles and Best Practices." In: Bozzon, A., P. Cudre-Maroux, C. Pautasso (eds), Web Engineering, ICWE 2016, Lecture Notes in Computer Science, vol 9671. Springer. Accessed 2020-02-15.
- Rozlog, Mike. 2010. "REST and SOAP: When Should I Use Each (or Both)?", April 01. Accessed 2020-02-10.
- Sandoval, Kristopher. 2016. "What is the Richardson Maturity Model?" Nordis APIS, April 26. Accessed 2020-01-20.
- Stowe, Mike. 2017. "Building Your API for Longevity, Part 2: Best Practices" NGINX, January 11. Accessed 2020-02-04.
- Thijssen, Joshua. 2020. "What is the Richardson Maturity Model?" Restcookbook. Accessed 2020-01-20.
- Vincy. 2019. "PHP RESTful Web Service API – Part 1 – Introduction with Step-by-step Example", February 19. Accessed 2020-02-10.
- W3Schools. 2020. "Richardson Maturity Model and REST Technologies." W3Schools. Accessed 2020-02-04.
- Zdenek, Nemec "Z". 2016. "API Maturity." Medium, April 16. Accessed 2020-01-20.
Further Reading
- Richardson, Leonard. 2008. "Act Three: The Maturity Heuristic." Crummy. Updated 2019-01-16. Accessed 2020-02-02.
- Fielding, Thomas Roy. 2019. "Richardson Maturity Model." RESTfulAPI.net. Accessed 2020-02-02.
- Fowler, Martin. 2010. "Richardson Maturity Model." ThoughtWorks, March 18. Accessed 2020-02-04.
Article Stats
Cite As
See Also
- Representational State Transfer
- RESTful API
- GraphQL
- Simple Object Access Protocol
- Amundsen Maturity Model
- Microservices