Richardson Maturity Model

The Richardson Maturity Model (RMM) is a maturity model suggested by Leonard Richardson to assess the maturity of a API service. In other words, the Richardson Maturity Model can be used to determine how well a Web service architecture adheres to REST principles. Follow this link to deep dive into REST.

It defines the following four levels (0–3) based on URI, HTTP verbs, and hypermedia.

Level 0: Swamp of POX
Level 1: Resources
Level 2: HTTP verbs
Level 3: Hypermedia controls

Each layer builds on top of maturity of the layer below. The higher the API in the level, the more mature it is.

Level 0: Swamp of POX #

This is the lowest level of maturity. At this level, the API is characterized as having a single URI for all its operations. The messaging is in XML, JSON, TEXT or any format. At this level of maturity, the POST method is used for sending the requests to the server. SOAP and XML RPC are examples of services at Level 0 maturity. HTTP is used as the transport system for remote interactions.

Level 0 API Examples:


POST      /createService  - create account, customer etc
POST      /GetService  - Get account info, customer info etc

At this level the API is no where close to being RESTful.

Level 1: Resources #

Introducing Resources and individual URIs to act on those resources is the first step towards RESTful maturity. So instead of one URI for all the services, each resource will have its own URI for the intended action.

Even at this level, POST is the only HTTP method for all API calls.

Level 1 API Examples:


POST      /createCustomer create customer
POST      /getCustomer create customer
POST      /createAccount create account
POST      /getAccount create account

Level 2: HTTP Verbs #

Instead of using POST method for all the API calls, at this level API is implemented with appropriate HTTP VERBS. The API moves towards a mature model compared to Level 0 and Level 1 and it uses HTTP verbs more closely to how they are used in HTTP itself.

Now the API is much easier to understand and from the HTTP VERB it is clear on the action done on each resource. Also the reource naming is standardised by dropping the action from resource name.

Level 2 API Examples:


POST      /customers create customer
GET      /customers get customers
PUT      /customers/{customerId} update customer
DELETE /customers/{customerId} delete customer
POST      /accounts create account
GET      /accounts get account
PUT      /accounts/{accountId} update account
DELETE      /accounts/{accountId} delete account


GET: For obtaining data. Idempotent

PUT (Idempotent): To update data. It will update the entire instance. Idempotent. Can be used for both creating and updating. Commonly used for updating (full updates). Always include the whole payload in the request. It’s all or nothing. PUT is not meant to be used for partial updates

PATCH (Idempotent): To update data. It will update partial data of an instance.

POST (Not idempotent): To store data.

DELETE (Idempotent): To delete an instance.

In addition to the use of HTTP verbs, Level 2 also introduces the use of appropriate HTTP response codes to indicate the status of a request call. If a resource was successfully created, the API returns a HTTP status code 201. If the API call on a resource was successful, HTTP status code 200 is returned. If the operation on a resource resulted in an error, an appropriate 4xx or 5xx status code should be returned in the response.


1xx: Informational
2xx: Success
3xx: Redirect
4xx: Client error
5xx: Server error

More information on HTTP VERBS

Level 3: Hypermedia Controls #

This is the final level for an API maturity according to the Richardson Maturity Model (RMM) and most of the RESTful APIs out there are examined to be a LEVEL 2 maturity model API.

For a REST API to be LEVEL 3, the API should implement the HATEOAS (Hypermedia As The Engine of Application State) concept. HATEOAS is an extension of REST which has additional constraints, allowing for more dynamic architectures.

HATEOAS makes APIs self-descriptive. In other words, it answers the question of ‘what to do next?’. All actions, which can be performed on resources are described in the representations of the resources in the form of links. These links can be navigated and called upon.

So rather than the client having to know where to post the next request, the hypermedia controls in the response tells how to do it. The semantics of the resources is provided by media types. This is why the HATEOAS style is also known as the hypermedia controls.

An advantage of using HATEOAS is makes it is easy to update and make changes in this architecture without breaking clients.

Level 3 API Examples:


GET      /accounts/12345 get account

Response:


HTTP/1.1 200 OK
Content-Type: application/vnd.progpub.account+json

{
    "account": {
        "accountId": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "rel_links": {
            "deposit": "/accounts/12345",
            "withdraw": "/accounts/12345",
            "transfer": "/accounts/12345",
            "close": "/accounts/12345"
        }
    }
}

In order to implement better REST APIs, understand what it is and learn the industry best practices.