Monday, April 27, 2015

The Richardson’s REST Maturity Model (RMM)

While reading the book ASP.NET Web API 2, Building a REST Service from Start to Finish, I came across a maturity model for REST known as the Richardson’s REST Maturity Model. The aim of the maturity model is to define an improvement pathway for developers to build RESTful web services. The pathway is scattered across 4 levels, starting at Level 0 going up to Level 3. Each level defines an improvement to building RESTful web service as follows:

Level 1 – Having unique URI for resources
Level 2 – Using HTTP Verbs to define action
Level 3 – Hypertext Controls known as the acronym HATEOAS (Hypertext as the Engine of Application State)

For the sake of clarity, I will be using an Employee web services and define a list of services/resources/methods exposed by it. At each level, I will demonstrate how the services/resources are improved by applying the principle defined in that level.

Level 0
At level 0, the web service resembles the SOAP/RPC style service. That is, there is a single URL of the web service and it supports a single HTTP verb. To access the different method on the web service, the client will add the specific method name in its header or as a parameter to the request. The following show a list of resources exposed by a level-0 web service

Method on ServerURIHTTP Verb
CreateEmployee/v1/employeService.asmxPOSTInformation via WSDL
GetEmployee/ v1/employeService.asmxPOSTInformation via WSDL
GetEmployeeTask/ v1/employeService.asmxPOSTInformation via WSDL
SearchEmployee/ v1/employeService.asmxPOSTInformation via WSDL
UpdateEmployee/ v1/employeService.asmxPOSTInformation via WSDL
DeleteEmployee/ v1/employeService.asmxPOSTInformation via WSDL

Level 1
At level 1, the aim is to define a particular resource for a corresponding method on the web service and therefore each individual resource is accessed via a unique URI as follows:

Method on ServerURIHTTP Verb
CreateEmployee/ v1/employeePOSTInformation via WSDL
GetEmployee/ v1/employee/225POSTInformation via WSDL
GetEmployeeTask/ v1/employee/225/tasksPOSTInformation via WSDL
SearchEmployee/ v1/employeePOSTInformation via WSDL
UpdateEmployee/ v1/employee/225POSTInformation via WSDL
DeleteEmployee/ v1/employee/225POSTInformation via WSDL

Level 2
In level 1, we have used the HTTP verb POST for all the resources. In some cases there might even be GET verb and a mixture of both. Hence we are not really defining what each resource is doing. Level 2 addresses this issue by using HTTP verb to provide a notion on the kind of operation being applied by the resources. The 4 mainly used HTTP verbs are GET, POST, PUT and DELETE:

GET – Get an employee(s) defined by unique URI
PUT – Replace or create an employee
POST – Create a new employee
DELETE – delete an employee

Applying HTTP verb to our employee web services will result in the following:

Method on ServerURIHTTP Verb
CreateEmployee/ v1/employeePOSTInformation via WSDL
GetEmployee/ v1/employee/225GETInformation via WSDL
GetEmployeeTask/ v1/employee/225/tasksGETInformation via WSDL
SearchEmployee/ v1/employeeGETInformation via WSDL
UpdateEmployee/ v1/employee/225PUTInformation via WSDL
DeleteEmployee/ v1/employee/225DELETEInformation via WSDL

Level 3
To access a website on the internet, we are only required to remember its root URL. From this point, it is easy to navigate throughout the website to obtain the resources required. Level 3 brings the concept of discovering resources that can be carried out on a particular employee, providing a way for making the protocol more self-documenting. 

For e.g. a request to the resource SearchEmployee (/v1/employee – GET) might return the following result:


Each employee contains several link elements that define a list of resources available on the particular employee. The point of level 3 is to tell us what can be done next and which URI to access. The advantage of this is client application does not hard code URL on their side to perform operation but rather depend on the link element. On server side, the URL for the resource can be changed without any impact on the client.

Applying the 3 levels of the RMM, according to me, provide a means of defining a web service that is self-explanatory to all uniquely identified resources exposed and providing context to each resource defined.

Reference: Chapter 2 ASP.NET Web API 2, Building a REST Service from Start to Finish

No comments: