REST API design — Richardson Maturity Model

Leonard Richardson has defined a Model to determine an REST API maturity, called Richardson Maturity Model.

There are 4 levels of maturity.

LEVEL 0: THE SWAMP OF POX

The Swamp of POX characteristics:

• the API exposes only one interface (or endpoint, or URI) which is used by all types of operations
• the method is POST
• the request and response messages are in plain old XML format
• the communication is in the form of RPC (Remote Procedure Call) over HTTP or SOAP (Simple Object Application Protocol) over HTTP

LEVEL 1: RESOURCES

To improve the communication performance, multiple URIs (Unique Resource Identifier) are employed.

• one specialized URI treats one type of operation
• only one HTTP verb: POST is used for all types of operations

LEVEL 2: HTTP VERBS

To improve the communication performance, multiple URIs (Unique Resource Identifier) are employed.

• one dedicated URI treats one type of operation
• different HTTP verbs are used: GET, POST, PUT, PATCH, DELETE

> GET: Retrieve an item or a collection

> POST: Create an item or a collection

> PUT: Update an item (PUT is idempotent which means if an item already exists, PUT will replace it)

> PATCH: Partial update on an item

> DELETE: Delete an item or a collection

LEVEL 3: HYPERMEDIA CONTROLS

Hypermedia controls provides HATEOAS (Hypermedia As The Engine Of Application State) on top of “HTTP Verbs”.

It means the clients with previous little or no knowledge of the API, should be able to use it.

And HATEOAS make it possible in providing navigational links, relevant actions to describe the use cases of different resources in the API.

Here is a comparison between an API without HATEOAS and another API with HATEOAS.

The advantage of HATEOAS is that you can see the hrefs and methods to be used to achieve the purpose of different rels.