Defining and Positioning the API on Richardson Maturity Model

Some of my LinkedIn connections did discussions with me about the previous article; these discussions were about the following:

• Most of the web APIs which we are worked on are not conformed with REST rules.
• It is very hard to adhere to those constraints.
• They claim that I judged that their web-APIs are bad.

Actually, I’m not here to judge either the APIs good or bad. As I mentioned in the previous article REST is an architecture style, so you would benefit from its advantages if you decided to use it, which they are:

Benefits of REST APIs

• The separation between client and server, which helps apps be more scalable.
• Statelessness, which makes API requests independent, very specific, and detail-driven.
• Endpoint URLs are standardized and unified along with the system, making app client developers not dependent on server documentations.

“Actually, I have a bad experience related to this point, I was suffering from integrating with telecom famous systems that don’t follow REST architecture, I wasn’t able to use API without contacting system developers to describe me the suitable URL endpoint, API request, and the response.”

• Lightweight, it relies on the HTTP standard, which means it’s format-agonistic and you can use XML, JSON, HTML, etc.

Indeed, the benefits of REST APIs are endless.

Let’s know how positioning the REST API

You might not have encountered to position your web APIs based on the standard model, but you can use Richardson Maturity Model, it will help you position your current API implementation level and what are you missing to upgrade that level up. This model was built based on three factors to decide the maturity level of the service (URI, HTTP Method, HATEOAS).

Level 0

It is using HTTP protocol just as a transport protocol, without using the capabilities of the HTTP protocol. It doesn’t make use of any of URI, HTTP Methods, and HATEOAS (I will describe it below). Service has only a single URL and uses mostly POST verb (like most of the old web service and SOAP).

Example:

POST/ http://host/appointmentService        

The above URL is used for all manipulation operations on appointment service (CRUD) based on the request payload type as following:

• For getting appointments:

<getAppointmentRequest date = "2021-01-01" doctor = "Eslam"/>        

• For booking an appointment

<addAppointmentRequest>

 <slot doctor = "Eslam" start = "1400" end = "1450"/>

 <patient id = "123654"/>

</addAppointmentRequest>        

This level is also called “The Swamp of POX” or “The Swamp of Plain Of XML”. If your APIs point to this level, so, your APIs are not following REST APIs guidelines.

Level 1: Resources

In this level, each URI maps to the unique resource (1st REST constraint “Uniform interface” previous article), but it doesn’t use HTTP verbs anymore.

Example:

POST/ http://host/appointments/1234        

The above URL is used for getting the appointment number “1234” but the API provider doesn’t care about the HTTP verb.

POST/ http://host/appointments/        

 but this one is used for adding a new appointment.

Level 2: HTTP Verbs

In this level, the API map a URI for each specific and unique resource correctly uses correct HTTP verbs (GET, POST, PUT, etc.) and returns the right status codes. From my point of view, it is the start level to conform to the RESTful guidelines.

Examples:

• Getting all appointments

GET/ http://host/api/appointments

 200 OK (appointments)        

• Getting the appointment number 1234

GET/ http://host/api/appointments/1234 

 200 OK (appointment)        

• Book a new appointment

POST/ http://host/api/appointments/ 

 201 Created (appointment)        

Level 3: HATEOAS

This is the final level; it is the most mature API level which encourages discoverability by supporting HATEOS (Hypermedia As The Engine Of Application State) that makes the response is self-descriptive.

HATEOS is a constraint of the REST application architecture that distinguishes it from other network application architectures. It provides metadata that descript the response type and links that help in navigation through a resource and its related resources as well as available actions. This way a client doesn’t need to know how to interact with an application for different actions, as all the metadata will be embedded in responses from the server.

To understand it better let’s look at the below response of retrieve user with id 123 from the server:

{
"name": "Eslam Sayed",

"links": [

{
  "rel": "self",
  "method": "GET",
  "href": "http://localhost:8080/user/123",
  "types":["text/xml","application/json"]
},
{
  "rel": "posts",
  "method": "GET",
  "href": "http://localhost:8080/user/123/posts",
  "types":["text/xml","application/json"]
},
{
 "rel": "address",
 "method": "GET",
 "href": "http://localhost:8080/user/123/address",
 "types":["text/xml","application/json"]
},
{
 "rel": "self",
 "method": "UPDATE",
 "href": "http://localhost:8080/user/123",
 "types":["text/xml","application/json"]
}

   ]

}        

Best practices to implement mature REST APIs

There are a lot of best practices we have follow them to implement a mature REST API, one of the most important one is “Consistency”

Consistency is the key

Use consistent resource naming conventions and URI formatting for minimum ambiguity and maximum readability and maintainability.

Let me continue describing the best practices in the next article. See you there 😊

References:

https://martinfowler.com/articles/richardsonMaturityModel.html

https://en.wikipedia.org/wiki/Representational_state_transfer#Layered_system

https://restfulapi.net/richardson-maturity-model/

https://www.mulesoft.com/resources/api/top-3-benefits-of-rest-apis