Scaling the API design review process at Google

Application programming interfaces (APIs) expose functionality and data to developers. Despite their importance, APIs are often hard to use. One particular study found that 88% of apps in the Google Play store that use cryptographic APIs contain at least one mistake. Incorrect use of APIs not only affects developer productivity (side note: Badly designed APIs have a higher learning curve.), but can also cause bugs and security issues. To make matters worse, badly designed APIs are also hard to fix, as any change may potentially break software that depends on it.

A good API design and review process can help developers avoid such problems. At Google, developers have been using API Design Reviews as part of an Apiness (API Happiness) programme to improve the quality of their APIs. These reviews consist of independent, experienced API reviewers shepherding an API owner through a series of iterative heuristic reviews that compare designs against pre-established Google standards.

Although participants were generally positive about this process, the process was largely manual, which meant that the approach did not scale well: as the number of participants grew, so did the turnaround time from review kick-off to formal sign-off and the inconsistency in reviewer guidance, due to constantly evolving style guides and best practices. Another major issue was that reviews often began too late, which meant that feedback came too late. In some cases, the review process forced teams to start over when they thought they had done a good job on their design and would be quickly stamped with approval!

To remedy these issues, Google introduced an API governance programme, which I briefly summarise below.

The updated API governance programme at Google consists of a four-pronged approach:

1. API improvement proposals (AIPs) that provide a set of rules that can easily be cited by reviewers.

2. An API linter that automatically checks APIs for violations of AIPs and provides developers with instant feedback during development.

3. An API readability programme that creates an official pool of qualified reviewers.

4. The original API design reviews as a final large design catch-all.

Inspired by Python Enhancement Proposals (PEPs), Google’s existing style guides were rewritten into concise rules. These rules were then published on aip.dev in order to create an unambiguous style guide that helps engineers design good APIs, and that can be easily referenced, e.g. aip.dev/122.

AIP guidelines use RFC 2119 requirement level keywords (side note: Must, must not, should, etc.) and often include concrete examples to make sure that readers fully internalise and understand them.

For the API standards to stay relevant, they must be constantly updated, either via new AIPs or via changes to existing AIPs. For this, the AIP process allows various stakeholders (technical leads, AIP editors, and API owners) to submit and approve changes. Each AIP is assigned a state (draft, reviewing, approved, replaced, etc.) that clearly shows where it is in its life cycle.

While AIPs can be a valuable resource for API owners during the design process, they do not provide early feedback. Therefore, an API linter (linter.aip.dev) was introduced that codifies elements of the review process. The API linter is a static analysis tool that acts as a first line of defence when anyone checks in code, well before it ever hits an API reviewer. The linter can be run manually in a terminal, but is also integrated into Google’s internal code editor so that developers get immediate feedback as they type.

Not only does the linter help enforce AIPs and allow minor design flaws to be solved early in the process, but it also frees up API design reviewers to focus more on larger, more novel API design decisions.

Google has a company-wide “Readability” training process, where experienced engineers can become certified to train other engineers in how to write readable, idiomatic code in a particular language.

To increase the pool of qualified API reviewers, the concept of “API Readability” was introduced. This primarily serves as a stamp of approval that a person is qualified to review APIs and helps engineers justify their involvement in API governance (side note: It’s all based on volunteering), but also creates more awareness of the existence of AIPs.

The updated API governance programme was evaluated using a large-scale survey and follow-up interviews with a subset of survey participants.

Respondents were largely positive about the API governance process. They consistently reported that API governance improved both the quality of API designs and the process of building APIs.

About 60% of participants are content with the pace at which API design reviews now take place. Interestingly, newer users often felt that the process is still a bit slow as they are still learning to navigate through the recommendations made in AIPs, while more experienced engineers feel that the process actually saves time as they don’t need to spend time arguing with others why APIs need to be designed a certain way.

Respondents were very positive about the AIPs, which answer most of their questions about designing APIs. Those who had interacted with the linter (about 80%) found that the linter not only helped them design better APIs, but also impacted the way they approached API design by making it more iterative. Finally, a large majority of respondents agrees that API Readability meaningfully improves the quality of APIs.

All in all, participants in the study generally agree that API governance is necessary for enforcing API consistency in large organisations. So if you work in a large organisation, you might want to give it a try too.