API Reviews: Scaling Up API Governance

API reviews are part of the overall API lifecycle. They are used to check that an API’s design matches the API design guidelines. API reviews are also an important step in making sure that the API landscape evolves and grows in a coherent way.

Designing useful and usable APIs

API reviews are only one step in the overall lifecycle. Before they happen, an overall design process has to ensure that a useful API is being designed. This typically happens by aligning the API with a business capability map, which allows to clearly identify the business purpose and value of the API. Once that value-oriented alignment exists, the next goal is to now create a usable API for this value proposition.

Usability of an API is both a question of how usable the API itself is, as well as how usable it is as part of the API landscape that it is a part of. This is where API guidelines often enter the picture:

On the one hand, they make it easier to design usable APIs by addressing common design tasks. On the other hand, they also create a more usable API landscape by making sure that APIs across the landscape follow the same design principles.

API reviews as a collaborative process

Apart from resulting in better APIs, API reviews are also an important organizational tool. They help API teams learn from the review process, but they also allow them to improve the review process by giving teams the opportunity to propose alternative solutions or new ways of solving problems.

One important aspect of API reviews therefore is to have the right people participate in the review.

In order for the collaboration process to work well, it is important to support API teams in their API design tasks. They should have tools available (such as, for example, API validation tools that automatically check for conformance with guidelines), meaning that the actual API review can focus on the interesting questions instead of having to spend time with relatively mechanical checks that can be automated.

Scaling API reviews

The overall idea of an API review is relatively simple, but it is also important to make sure that the review process can scale. It should not become a bottleneck in the API design and development process. What can be done to scale the review process?

Have a checklist that teams can use to make sure that they are completing all tasks that are required to enter the API review.
Provide standardized building blocks which can be easily reused by teams. These should be patterns that are part of many API designs (popular examples would be how to do pagination or how to represent error messages).

It is also important to make sure that API reviews are conducted only when all stakeholders are present. Scheduling reviews effectively and without building up a backlog means that roles of review participants must be well-defined, and that people in these roles see the reviews as a valuable step on their API journey, and not as a mandated step that they would prefer to avoid.

One big aspect of making sure that teams embrace the review process is to develop and constantly refine the ways in which tasks are being automated as much as possible, so that reviews can focus on discussing interesting facets of the API design.

It is also important to quickly publish the results of the review: Were there any changes to the API? If yes, why and what can we learn from these changes? Is the API review process getting changed as a result of this particular review?

API reviews are a central element of feedback to and from the API design guild. Your organization may have a different name for this group, but it is important to have a group of people who compile and manage the organizational patterns and practices of how APIs are designed.

The API design guild can discuss issues that get raised during the review process, and they are the ones who should decide on how patterns and practices are changed.

Conclusions

API reviews play an important role in the API lifecycle. They are important for the API teams so that they can create a usable API that fits well into the API landscape. They are also an important collaboration mechanism to make sure that API design patterns and practices are shared and evolved within the entire organization.

If you want to learn more about API reviews, in the following video Ikenna Nwaiwu of 10x Banking explains the ideas and the practicalities of API reviews in more detail.