The more APIs an organization has, the more critical API governance — the practice of standardizing and coordinating APIs across an organization — becomes.

An invaluable asset in many organizations’ governance strategy is an API style guide, which describes standards and best practices for all areas of API design. Having an API style guide could help ensure consistency, maximize performance, and improve overall security.

Although a style guide might sound simple, difficulties begin to arise as the number of individuals and APIs in an organization grows. For one, a serious effort is required to ensure the style guide remains structured as new guidelines are added for specific business areas. Additionally, it becomes challenging to manage feedback and change, especially if the style guide takes the form of a simple text document.

The engineers over at Google have come up with their own approach to the API style guide, called API Improvement Proposals. In this article, we’ll take an in-depth look at what these proposals cover, what they look like, how they’re managed, how you can implement them, and the benefits they offer.

What Are API Improvement Proposals (AIPs)?

API Improvement Proposals, or AIPs, are documents outlining Google’s guidelines for API design. Most AIPs focus on universal design standards — such as naming of resources, pagination, or error handling — which are applied across all of the organization’s services. However, some AIPs describe standards specific to certain product areas, as well as meta-AIPs (which describe AIPs themselves). This is also the case for Python Enhancement Proposals (PEPs), which are likely to have inspired AIPs.

Since every AIP is assigned a number between 1 and 9999, you can get an idea of the scope of these proposals by looking at the blocks that Google has reserved:

General

• 1–99: Meta-AIPs
• 100–999: General API design

Google Product Areas

• 2700–2799: Apps (GSuite)
• 2500–2599: Cloud
• 3000–3099: Actions on Google
• 3200–3299: Firebase
• 4100–4199: Auth libraries
• 4200–4299: Client libraries
• 4600–4699: Geo

For those looking to use AIPs to manage internal design guidance, Google has also reserved numbers 9000 through 9999 for private design documents. Otherwise, all AIPs are made public at https://google.aip.dev.

What Does an AIP Look Like?

So far, so good: we’ve got a collection of documents that describe Google’s API design guidelines. So, what makes the AIP approach to API governance special? Is it what the documents themselves look like? On the contrary, AIPs are — visually — rather mundane:

Aside from the metadata on the right-hand side, AIPs are simple text documents that use basic Markdown formatting. They usually consist of a few subheadings (depending on the subject), as well as a short changelog at the end.

Stylewise, perhaps the most notable convention is the frequent and appropriate use of requirement words — “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” — as defined in RFC 2119.

Stakeholders, Lifecycle, and Management

Before we get into the benefits of AIPs, let’s talk about some of the basics.

Stakeholders

There are multiple stakeholders involved in the creation of every AIP. Of course, there are the proposal authors, who are often APIs producers. Not only do authors conceive the idea for the proposal, but they also suggest its scope and content. Additionally, there are the editors, who determine whether an AIP is appropriate and help to refine the best practices included within. At the time of writing, there are just four AIP editors.

Lifecycle

In terms of lifecycle, AIPs are also relatively straightforward — every proposal has one of seven different states at any given moment:

• Draft — Its authors are determining the scope and content of the AIP.
• Reviewing — The editors are reviewing the AIP. Editors may provide feedback at this stage.
• Approved — The AIP has been accepted by the editors. Google engineers should follow the guidelines within the proposal.
• Withdrawn — The AIP has been withdrawn by its authors. New authors may continue its development.
• Rejected — The AIP has been rejected by the editors.
• Deferred — The AIP has not been updated for a significant period of time.
• Replaced — The AIP has been replaced by another AIP.

These are similar to the states used to describe Python Enhancement Proposals, with a few small exceptions.

Management

When it comes to how AIPs are managed, things start getting interesting. First of all, AIPs aren’t just a collection of documents sitting on a Google Drive somewhere. No, in fact, they’re all files hosted and edited in a dedicated GitHub repository. The public-facing AIP library at https://google.aip.dev/ is simply a static rendering of these files.

This makes it possible to use all of GitHub’s great features to manage the creation, modification, and discussion of AIPs. For example, all new proposals start their lives out when the author(s) open an issue. Similarly, feedback for existing AIPs is submitted by opening an issue. Finally, GitHub’s commit history takes care of change management.

What Are the Benefits of Using AIPs?

Although they look simple, AIPs have succeeded in improving consistency across Google’s APIs. After some analysis, we think we can attribute this improvement to three different benefits of AIPs:

Structured

It’s tempting to collect up design guidelines in a few text documents and throw them up on the cloud; however, it’s clear that there’s considerably more structure to the AIP approach. Not only do the meta-AIPs lay out how the guidelines are divided across AIPs, but they also define standards for the proposals themselves, thus ensuring they are easy to consume.

Collaborative

AIPs are a collaborative effort featuring multiple authors (who are often API producers working on the front-line) and different editors. This means consensus is established early-on within a group of varied contributors. Not to mention, anyone can provide feedback by opening an issue on GitHub.

Iterative

Hosted on GitHub — which describes itself as a version control platform — AIPs are always ready to be iterated on. There’s no reinventing of the wheel here; it’s just GitHub doing what it does best — managing change!

Implementing AIPs Internally

If you think AIPs could benefit your organization, the good news is that Google is happy for you to implement them. Simply fork the GitHub project, change a few lines in the _config.yaml, and off you go! Since the AIPs will be hosted on your own domain, you can add, delete, or edit to your heart’s desire.

For more information about adopting AIPs, see the official guide.

Final Thoughts

An essential part of any API governance program is a comprehensive style guide, which describes the standards and best practices that developers across the organization should follow. Google’s API Improvement Proposals are a unique take on the style guide, leveraging GitHub to enable collaborativeness and iterative improvement.