The Richardson Maturity Model

Have you ever though of how RESTful your RESTful APIs (okay, that was a mouthful) are? A system/API is only considered RESTful when it adheres to all of the required constraints, but are most "RESTful" APIs really RESTful? Do we take the API's author's word? How do we determine the RESTfulness of an API?

The Richardson Maturity Model is an excellent tool to help us determine the RESTfulness of an API. The Model was created by Lenard Richardson, and is used to grade the RESTful APIs by RESTful maturity.

Maturity Levels:

Level 0:

Also known as the swamp of POX (Plain Old XML). This level states that implementing protocol HTTP is strictly used for remote (between client and server) interaction using a single URI, without indicating the application state.
PRC-Style implementations like SOAP and XML-RPC are evident of Swap of POX in which we use POST only to a single API entry point and then let the API/service handle or re-route the call based on the body of the request.

Level 1 (Resources):

Level 1 expands on level 0 where there is a single URI. On this level, multiple URIs are used and each URI is mapped to a specific resource.
HTTP POST is only used in this level.
For example, a post (as in a blog post) resource would map to http://domain.com/api/posts to get a list of posts regardless of the author while http://domain.com/api/posts/{authorId} gets a list of posts by a specific author using their Id as the identifier.

Level 2 (Verbs):

for an API to reach this maturity level, the correct HTTP methods and their respective status code (GET, POST, DELETE, PUT and PATCH) must be used as intended by the HTTP protocol.
A successful GET must return status code 200 as OK, and a successful POST must return status as 201 created.

Level 3 (Hypermedia):

This level states that an API must support Hypermedia as the Engine of Application state (HATEOAS):
Hypermedia level is the holy grail of all maturity levels. It states that APIs must use hypermedia links to provide the client with discoverability options.

XML:

HTTP/1.1 200 OK
<?xml version="1.0"?>
<Account>
<Number>1290345</Number>
<Balance currency="CAN">100.00</Balance>
<link rel="Deposit" href="/Account/1290345/Deposit" />
<link rel="Withdraw" href="/Account/1290345/Withdraw" />
<link rel="Transfer" href="/Account/1290345/Transfer" />
<link rel="Close" href="/Account/1290345/Close" />
</Account>

JSON:

{
  "Account": {
    "Number": "1290345",
    "Balance": {
      "-currency": "CAN",
      "#text": "100.00"
    },
    "link": [
      {
        "-rel": "Deposit",
        "-href": "/Account/1290345/Deposit"
      },
      {
        "-rel": "Withdraw",
        "-href": "/Account/1290345/Withdraw"
      },
      {
        "-rel": "Transfer",
        "-href": "/Account/1290345/Transfer"
      },
      {
        "-rel": "Close",
        "-href": "/Account/1290345/Close"
      }
    ]
  }
}

In the above example, after a successful GET, the client receives the options/links to Deposit, Withdraw, Transfer and Close operations on this specified account.

Additional resources:

http://sammyageil.com/post/Lets-talk-about-REST

http://restcookbook.com/

Comments (2) -

James Robertson 7/8/2016 12:57:18 PM

The problem with HATEOAS is that its not easy to implement.
I have seen many architects promote their own ideas on how to approach this constraints.

Sammy Ageil 7/12/2016 8:20:40 AM

Hi James,
Having many options to approach a paradigm or a constraints doesn't necessarily equates to application difficulties.

Add comment