Richardson Maturity Model in REST API
The Richardson Maturity Model is a model developed by Leonard Richardson in 2008 to categorize and rank the architectural maturity of web APIs based on their adherence to REST (Representational State Transfer) principles. REST is a style of software architecture for distributed systems, often used in web services development. The Richardson Maturity Model consists of four levels, each representing a different level of adherence to REST principles:
Level 0
The Swamp of POX (Plain Old XML): At this level, APIs use HTTP primarily as a tunnel for remote procedure calls (RPCs). They typically have a single endpoint for all operations and rely heavily on HTTP POST requests, often sending and receiving data in non-standard formats like XML. There’s little or no use of HTTP methods like GET, POST, PUT, DELETE, etc., and URI structures don’t follow any consistent pattern.
Level 1
Resources: At this level, APIs start to use HTTP methods like GET, POST, PUT, and DELETE more appropriately. However, they still don’t make full use of HTTP features like proper URI structures. Each endpoint might represent a single resource, but the URIs might not be very intuitive or RESTful.Ex: api/users, api/orders, api/songs, api/users/123, etc.
Level 2
HTTP Verbs: At this level, APIs make full use of HTTP methods for different CRUD (Create, Read, Update, Delete) operations. Resources are identified using URIs in a more meaningful and consistent way. This level represents the basic understanding of REST principles, including the proper use of HTTP status codes and headers.
Example: api/orders with POST for create, api/orders PUT (or PATCH) for update, etc.
Level 3
Hypermedia Controls (HATEOAS – Hypermedia as the Engine of Application State): At this highest level of maturity, APIs not only expose resources and operations but also provide links or hypermedia controls that allow clients to navigate the API dynamically. In other words, the API tells the client what it can do next by providing links to related resources or actions. This enables greater flexibility and evolvability of the API over time.
Example: api/products/1 could list all other operations such as PUT, DELETE, etc.
{
"id": 1,
"name": "Product 1",
"price": 10.99,
"links": [
{
"rel": "self",
"href": "/api/products/1",
"method": "GET",
"description": "Retrieve this product"
},
{
"rel": "update",
"href": "/api/products/1",
"method": "PUT",
"description": "Update this product"
},
{
"rel": "delete",
"href": "/api/products/1",
"method": "DELETE",
"description": "Delete this product"
}
]
}
Adherence to higher levels of the Richardson Maturity Model typically leads to more scalable, flexible, and easier-to-maintain and evolve APIs. However, reaching level 3 can be challenging and often requires careful API design and implementation of hypermedia controls.
Richardson Maturity Model principle is not limited to ASP.net Core APIs it’s for all REST APIs. With ASP.net Core APIs, you can easily archive levels 2 and 3 without any third-party library or implementation. However, Level 3 can sometimes be an overkill and can increase development time. You can use one of these NuGet packages to make things easy.
As with any other principle, it’s not a MUST – you can choose what level you want to dive deep into. For enterprise APIs I think it is defiantly good to have Level 3, for others I think Level 2 is enough.
