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.
With HATEOAS, you can see the hrefs and methods to be used to achieve the purpose of different rels.
