While most developers are aware of Roy Fielding and REST, fewer may be aware of the Richardson Maturity Model. Though the Richardson Maturity Model is often considered more esoteric in comparison to its more famous compatriots, it can serve as a goalpost to achieving truly complete and useful APIs.

Today, we’re going to discuss the Richardson Maturity Model as designed by Leonard Richardson. The model identifies three layers — URI, HTTP Methods, and HATEOAS (Hypermedia) — to determine the maturity of a service. We’ll expand on these levels, what they entail, and what they result in. We’ll discuss the Richardson Maturity Model in the context of REST, and identify how the Richardson Maturity Model can help guide the API development journey.

Level 0 – The Swamp of POX

You may need more than SOAP to clean off from the Swamp of POX

The Richardson Maturity Model starts not at level 1, but at level 0 – the “swamp of POX.” POX in this case stands for Plain Old XML, and represents the most basic functionality expected of an API entering into the Richardson Maturity Model. At this level, HTTP is used as the transport mechanism for every remote interaction, but these interactions don’t utilize the mechanisms inherent in the web. HTTP serves as a basic tunneling mechanism alone.

At this level, all API interaction is essentially RPC, a back and forth XML conversation wherein every request and response is nothing more than a chunk of code. This may be useful in some cases, surely, but even in SOAP, the penultimate POX-centric solution, each iteration and evolution is nothing more than wrapping the HTTP process in a complicated envelope.

Level 1 – Resources

Utilize resources to begin the API maturation process

XML conversations work in some scenarios, but they’re not ideal for the complex tasks required of modern API interactions and offerings. For one, POX is inefficient, often transferring superfluous text. Second, by communicating over XML, you’re over complicating what should be an otherwise simple, efficient, and succinct communication.

Our first step towards rectifying these issues is to emerge from the swamp of POX by utilizing resources. Resources allow requests to be 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 complete sea change.

In POX, an ill-defined function is simply called from a large body, an aether-like miasma of collated resources and possible points of resolution, and then this function is defined with further complex arguments. By adopting resources rather than XML bodies for communication, we are establishing a type of object identity, calling a particular object and passing arguments to it that are specifically related only to its function and form.

Level 2 – HTTP Verbs

Correct HTTP verb usage

Now that we’ve moved towards resources, we can start looking at how we interact with those resources. In the POX approach, verbiage often doesn’t specifically matter. POST does what POST does, but GET can in many cases function in much the same way, resulting in an API that often delivers the same data to duplicate verbs. In Level 0 and Level 1, these verbs serve as a tunneling mechanism for your request – in those levels, this is fine, since all the API is really doing is conversing in XML with XML.

The problem, however, is that verbiage is different for a reason. Each verb — GET, POST, PUT, DELETE, etc — does something very specific, and these functions often deliver entirely different sets of results when properly addressed – failure to leverage HTTP verbs for their correct usages means that you’re losing a lot of potential functionality for no reason.

As a good example, both POST and GET in the POX approach will result in the same return – GET, however, is defined as a safe operation, which opens up a ton of functionality. One such functionality is caching, which can be used to great effect to reduce the amount of processing needed by the API, and an increase in transit efficiency by removing the need to respond to requests that will only generate the same result.

All of that is lost, of course, without designing your resources specifically around the verbiage and the expected response. By differentiating the leverage through design at level 2, we can take full advantage of such benefits.

Level 3 – Hypermedia Controls

HATEOAS delivers more links and information

For many developers, level 2 is “good enough”. Proper verbiage and a reduction in XML chatter dependence seems to result in an API that is basically in a usable state, and as such is where many developers feel comfortable with stopping. Unfortunately, this is missing the entire point of this exercise – the final step, level 3, grants certain benefits that should not be ignored.

Level 3 implements hypermedia, which can be used to great effect to extend the functionality of an API to new levels. By implementing HATEOAS (Hypertext as the Engine of Application State), we can make the API respond to requests with additional information, and link resources together for more rich interactions. These links can make user experience that much more rich, and can create a web of functionality that results in a more powerful, more efficient, and more useful.

Utilizing hypermedia also delivers the ability to update URI schemes without breaking clients, allowing for a greater amount of freedom for development change on the back end. This is not the case before level 3, but the benefits don’t stop there. The simple fact is that an API which does not utilize Hypermedia is functioning at its most basic, least useful level – the fundamentals may be on offer, but the API is self-limiting in the extreme.

The Richardson Maturity Model Guides Development

Beyond the reasons noted above, there’s an even greater reason to adopt the Richardson Maturity Model through to level 3. According to Roy Fielding, the creator of the concept of RESTful design, Hypermedia is a prerequisite of true REST. As such, reaching the final third level of the Richardson Maturity Model can be seen as a goalpost for development teams that desire a true RESTful conclusion.

All of that being said, the final level of the Richardson Maturity Model is not the end-all be-all for API design. REST is very useful, but there are some cases where SOAP makes sense, and in that case. Even in those cases, of which there are few, level 2 Richardson Maturity Model is still a very good goalpost to reach, as that is where an API comes to depend on resources rather than XML bodies and massive undifferentiated endpoints.

Here, we can see where the Richardson Maturity Model really shines. Yes, it’s final levels will result in a RESTful result – but ultimately, the Richardson Maturity Model is a great system by which the maturity of an implementation can be measured. With each maturity requirement of your implementation fluctuating largely due to the requirements of the user, the Richardson Maturity Model can be used as a sort of structure by which development can be guided towards a more complete, more mature result, irrespective of the foundational elements of the API itself.

It also adds structure for collaborative development. Any development will naturally start as less mature and evolve towards more mature. Guiding API design solely by features or economic motives without a structure in place can lead to issues. Therefore, technical development must be guided, and it must be structured with a goal in mind.

More important than these elements are the structures which fundamentally dictate whether the API is RESTful or not, whether it uses resources or not, and whether it respects standardized verbiage. The Richardson Maturity Model can function as a system to ensure adherence and promote maturity throughout the development lifecycle.

A Path Toward API Realization

Ahh, out of the swamp. This looks much better.

The Richardson Maturity Model is a visual way to gauge the competency of your API. In this article we dissected each layer: Plain Old XML, Resources, HTTP verbs, and hypermedia. Much like Maslow’s Hierarchy, the journey to realization is an upward climb; as your API moves higher, it becomes more fulfilled.

While the Richardson Maturity Model is not the only development model on offer in the API landscape, it’s core philosophies are hard to argue against. The simple fact that its ultimate goal, integration of Hypermedia, is considered by Roy Fielding himself to be a prerequisite for REST design should make anyone developing a REST application take notice.

Additionally, even when ignoring its RESTful attributes, the Richardson Maturity Model offers a goalpost for development that will result in greater, more fully designed APIs that respond in a more natural, effective, and powerful way.

Additional Resources

• Richardson Maturity Model: steps toward the glory of REST
• Richardson Maturity Model
• Act Three: The Maturity Heuristic