Understanding REST API Maturity Levels

6 MIN READ

February 08, 2022

6 MIN READ
monadsolutions.comsitepolicies

REST APIs use HTTP protocol to allow applications to communicate with each other via the internet. Those who want fast, robust, and scalable interfaces need to track REST API maturity levels. This begins by measuring the existing maturity using the Richardson Maturity Model.

A less-developed REST API may have problems with:

  • Misuse of HTTP actions, leading to slowdowns
  • Poor code organization, generating higher development and maintenance costs
  • Confusing API structure

In this article, you will learn how to measure REST API maturity levels and discover the advantages of higher-quality interfaces.

Measuring REST API Maturity Levels

A REST API can have four maturity levels, the lowest being Level 0 and the highest being Level 3. When deciding which maturity level is necessary for your REST APIs, consider the needs of the applications that will consume them. Below, we’ll go through each level and break down its distinguishing characteristics.

REST API Maturity Level 0

In the lowest maturity level, you can expect to find more (and disorganized) code, along with a mountain of resources used to maintain it. Also, there will often be problems processing requests.
All inquiries to fetch, update, insert, and delete data will be through POST. APIs at this level cannot use a wider range of functionalities.
You’ll also notice that at Maturity Level 0, there will only be one published URL for API access. Therefore, if there is a request to retrieve all users of an application, we would have the following URL:

https://appendpoint/users?action=list

The same happens if we are requesting to insert a new client. The URL used would be the same, with some changed parameters. Here’s an example of a URL to enter users:

https://appendpoint/users?action=add

Simple operations require excessive documentation at this level. That’s because the lack of clear structure and relationships forces too many customized demands in the URL. The code and its scalability may become unmaintainable in the future.

REST API Maturity Level 1

At this level, REST APIs become more organized. A URL exists for each requested resource. Here’s an example:

https://appendpoint/users

If an application requests one specific resource, the URL changes. The resource key will now appear at the end, as seen below:

https://appendpoint/users/1

If there is a relationship between this resource and a sub-resource, we would have the following example endpoint:

https://appendpoint/users/1/training-days

At Maturity Level 1, we can expect a great reduction of problems in the architecture. That makes development less complex, reducing costs. However, we still have only one operation verb used at this level, POST, which can lead to confusion and disruption.

Two female professionals reviewing timeline of new APIs’ launch on whiteboard.

REST API Maturity Level 2

At Maturity Level 2, REST APIs move beyond just POST requests to a more complete menu of options. There should be enough variety of HTTP verbs to allow for CRUD (Create, Read, Update, and Delete) operations. Among the most popular options, based on the REST architecture, are:

POST: Create a new resource.
GET: Fetch data from one or several resources.
PUT: Update all attributes of a resource.
PATCH: Partially update a resource.
DELETE: Remove a resource.
HEAD: Check if a resource exists.
OPTIONS: Check all types of operations available for a resource.

Using the verbs correctly will make the REST API more readable and easier to maintain.

REST API Maturity Level 3

Characterizing the highest level of REST API maturity is the application of HATEOAS (Hypermedia as the Engine of Application State). Essentially, this means systems can now see navigational links to information related to their queries.
Let’s look at an example, beginning with a request to add a new resource using the POST verb:

POST https://appendpoint/users/

We must also send the attributes, such as name and age, of the new client in the format required by the API.

POST https://appendpoint/users/
Request body:
{
     “name”: “User Name”,
     “age”: 20,
     “password”: “User password”
}

The API confirms the creation of a new client and brings all of that client’s data and its unique identifier.

POST https://appendpoint/users/
Response status: 200 OK
Response body:
{
     “id”: 100
     “name”: “User Name”,
     “age”: 20,
     “password”: “User password”
     “insertion_date”: “2021-07-28 00:00:00”
}

With HATEOAS applied in this REST API, the return will also bring all possible actions for this resource, along with its relationships with other resources and examples of how to access them.

POST https://appendpoint/users/
Response status: 200 OK
Response body:
{
“content”:
     {
          “id”: 100
          “name”: “User Name”,
          “age”: 20,
          “password”: “User password”,
          “insertion_date”: “2021-07-28 00:00:00”
     },
“_links”:
[
     {
          “href”: https://appendpoint/users/100
          “relationship”: “”
          “type”: “GET”
     },
     {
          “href”: https://appendpoint/users/100/training-days
          “relationship”: “training-days”, “results”,
          “type”: “GET”
     }
]
}

An API at Maturity Level 3 provides self-documentation. It is now easy for the API client to discover all possible actions for the resource. Just as a website informs the user about each resource on the screen they are navigating, a REST API at level 3 must do the same for the system that is consuming it.

Which REST API Maturity Level Do You Need?

If you want to build REST APIs for communication between your company’s software systems, aim for a high maturity level. This ensures simple and effective communication, as well as lower maintenance costs. Maturity Level 3, for example, guarantees well-organized REST APIs with easy-to-understand endpoints, intuitive features, scalability, and self-documentation.

Although a mature REST API brings enormous benefits, it is worth noting that high-maturity versions of this interface can suffer from problems related to exhaustion, such as over-fetching and under-fetching. However, new technologies exist to solve burnout, such as Microsoft’s OData and Facebook’s GraphQL.

Every organization is different, and you may still find yourself wondering how to build and leverage high-maturity REST APIs. Luckily, Programmers has over 30 years of experience developing a wide array of end-to-end digital solutions. Contact us today to lower maintenance costs and enjoy more organized REST APIs.

Stay up to date on the latest trends, innovations and insights.