Richardson Maturity Model classifies REST API maturity as follows
- Level Zero: These services have a single URI and use a single HTTP method (typically POST). For example, most Web Services (WS-*)-based services use a single URI to identify an endpoint, and HTTP POST to transfer SOAP-based payloads, effectively ignoring the rest of the HTTP verbs. Similarly, XML-RPC based services which send data as Plain Old XML (POX). These are the most primitive way of building SOA applications with a single POST method and using XML to communicate between services.
- Level One: These services employ many URIs but only a single HTTP verb – generally HTTP POST. They give each individual resource in their universe a URI. Every resource is separately identified by a unique URI – and that makes them better than level zero.
- Level Two: Level two services host numerous URI-addressable resources. Such services support several of the HTTP verbs on each exposed resource – Create, Read, Update and Delete (CRUD) services. Here the state of resources, typically representing business entities, can be manipulated over the network. Here service designer expects people to put some effort into mastering the APIs – generally by reading the supplied documentation. Level 2 is the good use-case of REST principles, which advocate using different verbs based on the HTTP request methods and the system can have multiple resources.
- Level Three: Level three of maturity makes use of URIs and HTTP and HATEOAS. This is the most mature level of Richardson’s model which encourages easy discoverability and makes it easy for the responses to be self-explanatory by using HATEOAS. The service leads consumers through a trail of resources, causing application state transitions as a result.
Where HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture that keeps the RESTful style architecture unique from most other network application architectures. The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text. This architectural style lets you use hypermedia links in the response contents so that the client can dynamically navigate to the appropriate resource by traversing the hypermedia links. This is conceptually the same as a web user navigating through web pages by clicking the appropriate hyperlinks to achieve a final goal. Like a human’s interaction with a website, a REST client hits an initial API URI and uses the server-provided links to dynamically discover available actions and access the resources it needs. The client need not have prior knowledge of the service or the different steps involved in a workflow. Additionally, the clients no longer have to hard code the URI structures for different resources. This allows the server to make URI changes as the API evolves without breaking the clients.
Naturally you would want to build to highest standard and provide level three REST API. That would mean providing a links field as in the following example below from GT-IDStorm API
The data payload as you can see from this sample is huge, compared to the actual data returned.
{
“value”: [
{
“id”: “63b2c70e-2bcb-4335-9961-3d14be642163”,
“name”: “Entity-1”,
“description”: “Testing Entity 1”,
“links”: [
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163”,
“rel”: “self”,
“method”: “GET”
},
{
“href”: null,
“rel”: “get_entitydefinition_byname”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/full”,
“rel”: “get_full_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163”,
“rel”: “delete_entitydefinition”,
“method”: “DELETE”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/attributes”,
“rel”: “create_attribute_for_entitydefinition”,
“method”: “POST”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/attributes”,
“rel”: “get_attributes_for_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/systems”,
“rel”: “create_system_for_entitydefinition”,
“method”: “POST”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/systems”,
“rel”: “get_system_for_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/63b2c70e-2bcb-4335-9961-3d14be642163/data”,
“rel”: “get_data_for_entitydefinition”,
“method”: “GET”
},
{
“rel”: “get_data_WithMissingSystems_for_entitydefinition”,
“method”: “GET”
}
]
},
{
“id”: “54bc1f18-0fd5-43dd-9309-4d8659e3aa91”,
“name”: “Entity-10”,
“description”: “Testing Entity 10”,
“links”: [
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91”,
“rel”: “self”,
“method”: “GET”
},
{
“href”: null,
“rel”: “get_entitydefinition_byname”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/full”,
“rel”: “get_full_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91”,
“rel”: “delete_entitydefinition”,
“method”: “DELETE”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/attributes”,
“rel”: “create_attribute_for_entitydefinition”,
“method”: “POST”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/attributes”,
“rel”: “get_attributes_for_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/systems”,
“rel”: “create_system_for_entitydefinition”,
“method”: “POST”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/systems”,
“rel”: “get_system_for_entitydefinition”,
“method”: “GET”
},
{
“href”: “https://localhost:44379/api/v1/entity/54bc1f18-0fd5-43dd-9309-4d8659e3aa91/data”,
“rel”: “get_data_for_entitydefinition”,
“method”: “GET”
},
{
“rel”: “get_data_WithMissingSystems_for_entitydefinition”,
“method”: “GET”
}
]
}
],
“links”: [
{
“rel”: “self”,
“method”: “GET”
}
]
}
For example if we remove the HATEOAS requirement that data returned for the same query would be
This would less data would have huge impact on the system as a whole performance, Less traffic on the network, less data to process and manipulate by the client and servers.
[
{
“id”: “63b2c70e-2bcb-4335-9961-3d14be642163”,
“name”: “Entity-1”,
“description”: “Testing Entity 1”
},
{
“id”: “54bc1f18-0fd5-43dd-9309-4d8659e3aa91”,
“name”: “Entity-10”,
“description”: “Testing Entity 10”
}
]
I usually implement the API to have and accept header with multiple options
- Application/json: returns just the data
- Application/hateoas+json: return the data with the hateoas (Links) data.
I also implement another resource or operation that provides the links structures
In Conclusion
I would recommend implementing the API to:
-
Support Level Two and Leve Three at the same time by using the accept header for the request to
- Application/json: returns just the data
- Application/hateoas+json: return the data with the hateoas (Links) data.
- Implement another resource or the root that would return the URLs (structures and operations) that are supported by the API.
As I found just support HATEAOS only would make the system pay heavy price on performance specially with large data loads while very few clients if any would utilize the links returned. I would love to hear your thoughts and experience on APIs with HATEAOS?
Genetic Thought Software Inc. 
One response to “Practical REST API Design, implementation and Richardson Maturity Model”
[…] Levels two and three in Richardson Maturity Model(see my previous post https://moustafarefaat.wordpress.com/2018/12/11/practical-rest-api-design-implementation-and-richard…😉 . This means based on the Accept header of the request return the results as […]