REST API Maturity Cube for Developer-Friendliest APIs

Companies and organizations usually need tools to measure how they are doing and what improvements are required to take the businesses to the next level.

The Maturity Model is one of the tools used by organizations to measure their capabilities in different areas and domains and assesses the requirements for improvements. The exciting thing about the maturity models is that they represent progressive upgrades from one step to another. Each new level provides new requirements in addition to the previous levels' requirements.

As of today, there are many maturity models exist, such as People Capability Maturity Model (PCMM), OPM3 (Organisational Project Management Maturity Model), the Sustainability maturity model, and the Capability Maturity Model Integration (CMMI).

Like many other concepts and tools, the Maturity model is derived from business and engineering domains into the software domain—for example, Open Source Maturity Model, Service Integration Maturity Model, and Modeling Maturity Levels.

In this article, we will be focusing on the Maturity of REST APIs. How to measure the design of an API, and what is needed to achieve a better one. But, we need to understand first the purpose of evaluating our APIs and the value of improving them.

APIs are built to be consumed by other developers. Accordingly, they must be developer-friendly, that are easily accessible and broadly understood, which can be achieved by fulfilling the following characteristics:

1. Tolerance: APIs must tolerate backend changes by abstracting the implementation details and reducing the dependencies between the consumers and the backends.
2. Reusability: APIs must be reusable by servicing different types of consumers and developers.
3. Security: APIs must guard the backend resources from any misuse.

Three Maturity models already exist, each addressing one characteristic at a time.

For the Tolerance characteristic, there is already a maturity model called Amundsen (AMM) that measures the APIs according to the level of data abstraction. Higher levels indicate higher API abstraction and decoupling from the internal implementation and, accordingly, higher tolerance.

For the Reusability characteristic, there is already a maturity model called Richardson (RMM) that measures the APIs according to their adherence to the REST Architecture. Higher levels indicate higher compatibility with REST Architecture, the further away from RPC style, and, accordingly, higher reusability.

It is important to notice that level three of both; Richardson and Amundsen are similar as they both focus on the use of hyperlinks which can participate in the Tolerance characteristic of the API. With Hypermedia, consumers can detect the URIs of the Resources dynamically without the need to maintain a long list of URIs. Accordingly, any changes to the Resources' URIs will not require changes to the client code.

For the Security characteristic, there is already a maturity model called Ideskog (IMM) that measures the APIs according to their level of security.

The most common levels I have seen are either zero or three, but it is infrequent to see levels; One and Two.

It would be best if you achieved a high maturity level in all three maturity models to provide the developer-friendliest API. For that purpose, we can combine the three maturity models into a single 3-dimensional cube where each dimension represents one of the mentioned models. Accordingly, we can have a dimension for Richardson Model, another for Amundsen Model and a third for Security Model.

To assess the Maturity of an API according to the Maturity Cube, you need to sum up the total of the three levels together where zero is the lowest maturity level, and nine is the highest maturity level:

API Maturity = RMM Level + AMM Level + IMM Level

For example, suppose the API has Level zero as per Richardson (RMM), Level zero as per Amundsen, and Level zero as per Ideskog (IMM). In that case, the accumulated Maturity for this API is zero, as per the below:

API Maturity = 0 + 0 + 0 = 0 (This API has the lowest maturity level)

Let's take another example; let's say the API has Level three as per Richardson (RMM), Level three as per Amundsen, and Level three as per Ideskog (IMM). In that case, the accumulated Maturity for this API is nine, as per the below:

API Maturity = 3 + 3 + 3 = 9 (This API has the highest maturity level).

Conclusion

This article taught you about the 3 Maturity Models that can guide you in building great APIs.

In addition, you have seen how the three models have been combined in a single three-dimensional cube where each dimension represents a single model.

You can use this cube and customize it according to your requirements. For example, Suppose your organization consistently achieves level three per the security model. In that case, you can build a two-dimensional matrix that addresses the data abstraction and REST architecture conformance and ignores the security, as it is always the same.