# Richardson Maturity Model

## Summary


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

Mar  
1998

Dave Winer introduces **XML-RPC**, a lightweight rival of SOAP. SOAP development is held up due to several disagreements. Hence, XML-RPC comes out first. About this time (February 1998), W3C releases **XML Version 1.0**. 

May  
2000

**Simple Object Access Protocol (SOAP)**, originally developed at Microsoft, becomes a W3C recommendation. It marks the beginning for web services between clients and remote web servers. SOAP is widely adopted by most emerging companies like Salesforce, Ebay and Yahoo. 

2000

Roy Fielding, unhappy with SOAP implementation comes out with a protocol neutral architectural style called **REST**. This is published as his PhD dissertation at UC Irvine. REST is just a set of design principles at this stage. 

2003

Amazon S3, a file hosting service, releases APIs with support for URI and HTTP verbs. But the design doesn't provide resource links. Instead, resources are marked by unique key-value pairs. 

2004

Adobe, Netflix and some other major service providers adopt web services design, supporting hypermedia links in their responses. This open API design is greatly appreciated. 

2008

After analysing hundreds of web service designs, Leonard Richardson comes up with a model that helps to distinguish between good and bad designs. His yardstick is purely based on API maturity. This model is popularly referred to as **Richardson Maturity Model (RMM)**. 

2015

News aggregators and media companies like The Guardian and Wall Street Journal upgrade their web services for better REST conformity. Now their services are compliant with Level 3 of the Richardson Maturity Model, with hypermedia controls. 

2016

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. 

2018

Adobe releases Hypermedia driven UI framework for remote web services called Granite UI. Granite UI is an umbrella name for UI projects to build a LEGO® architecture for UI, so that one can build complex web applications with much less code.