Why there is no such thing as the Richardson Maturity Model

One common yardstick used to measure the RESTishness of an API design is what has become known as the Richardson Maturity Model (or RMM). Originally known simply as the Maturity Heuristic, Leonard Richardson's scale defines the following levels of maturity of an API design:

• Level Zero: One URI, one HTTP method
• Level One: Many URIs, one HTTP method
• Level Two: Many URIs, each supporting many HTTP methods
• Level Three: Hypermedia

We can recognise Level Zero as RPC, or SOAP style APIs.

Level One APIs have the concept of resources (or representations), but all requests use one HTTP method (such as GET or POST). This fails to leverage the HTTP protocol to its fullest, and as Richardson notes, makes it very easy to destroy data by accident.

Level Two is probably the commonest level seen in production APIs today. It represents all of Fielding's mandatory REST constraints apart from HATEOAS.

Level Three is REST, including the hypermedia constraint. Though Richardson in his original discussion (https://www.crummy.com/writing/speaking/2008-QCon/act3.html) states:

"A lot of people settle for level two because hypermedia is difficult to understand and its value in the web service domain isn't as clear."

Unfortunately, the Richardson Maturity Model has been popularised by Martin Fowler in a somewhat bowdlerised form from the original. Unhelpfully, the graphic on his website, often reproduced, chooses to rename the levels above as:

• Level Zero: The Swamp of POX
• Level One: Resources
• Level Two: HTTP verbs
• Level Three: Hypermedia controls

Even if we accept the application of a maturity model to API design as being somewhat biased, implying as it does that REST APIs are more "mature" than RPC APIs (when in fact they simply serve different needs and purposes), there is little excuse for using pejorative terms like "swamp". "POX" also sounds unpleasant, but here simply means 'Plain Old XML'.

Either way, the popularised version of the RMM makes no distinction between resources and representations and only adds to the confusion between HTTP 'verbs' and HTTP methods, which the original does not.

Richardson himself at RESTFest 2015, in a talk subtitled "What Have I Done?", described the whole thing as "very embarrassing" and clarified that if you want to proceed up the steps of the Maturity Heuristic, you have to have either a technical reason or a political reason to do so. There is also no prize or "glory" at the top - sorry to disappoint. (https://vimeo.com/147237932)

Do please refer to Richardson's original work for more details on this model.

Thanks to Darrel Miller for pointing out Richardson's later talk.