AIP-8

AIP Style and Guidance

AIP stands for API Improvement Proposal, which is a design document providing high-level, concise documentation for API design and development. The goal is for these documents to serve as the source of truth for API-related documentation at Google and the way API teams discuss and come to consensus on API guidance.

AIPs are most useful when they are clear and concise, and cover a single topic or inquiry well. In the same way that AIPs describe consistent patterns and style for use in APIs, they also follow consistent patterns and style.

Guidance

  • AIPs must cover a single, discrete topic, and provide clear, actionable guidance.
  • AIPs must not duplicate or contradict guidance in another AIP.
  • AIPs may also cover what not to do, but should not cover only anti-patterns.
  • If AIP guidance is conditional (e.g. a design pattern such as Jobs), the guidance must clearly explain under what conditions the guidance should be followed.

Guidance contained within an AIP must be beneficial to one or more types of clients or their authors, including but not limited to:

  • Asset inventories which can be used to audit and analyze resources.
  • Command line interfaces for exploration and simple automation.
  • Custom controllers (e.g. auto-scalers) which poll live state and adjust resource configuration accordingly.
  • IaC clients for orchestration and automation of multiple resources.
  • Recommendation tools which provide guidance on which APIs are useful for specific use cases, and how to use them.
  • SDKs to interact with an API from a programming language, often used heavily for data-plane operations.
  • Security orchestration, automation, and remediation tools.
  • Simple scripts to automate or orchestrate tasks.
  • Test frameworks.
  • Tools that operate on resource data at rest.
  • Visual User Interfaces for visualization and one-off manual actions.
  • Users.

Examples of improvements include:

  • Requiring new proto annotations that enable more descriptive interfaces on clients (e.g. requiring singular and plural on a google.api.resource annotation).

AIP guidance must not be a significant detriment to a client's usability or implementation difficulty, or maintenance difficulty.

Examples of detriments include:

  • Introduction of a non-uniform pattern in a standard method such that all clients must introduce additional code without sufficient benefit (e.g. List behaves like this except for resources that start with the name Foo).
  • Renames of well-established fields for minor improvements in readability (e.g. rename expire_time to lapse_time since lapse is a common term in my service).

While the length of AIPs will necessarily vary based on the complexity of the question, most AIPs should be able to cover their content in roughly two printed pages.

File structure

AIPs must be written in Markdown, and must be named using their four-digit number (example: 0008.md). AIPs that serve a specific scope must be in the subdirectory for that scope.

AIPs must have appropriate front matter.

---
id: 8
state: reviewing
created: 2019-05-28
permalink: /8
redirect_from:
  - /08
  - /008
  - /0008
---

Front matter for AIPs must include:

  • The aip key:
    • id: Required. The ID for the given AIP, as an integer.
    • state: Required. The current state of the AIP, in all lower-case. The valid states are listed in AIP-1, and common states are draft, reviewing, and approved.
    • created: Required. The ISO-8601 date (yyyy-mm-dd) when the AIP was originally drafted, with no quotes.
    • updated: The ISO-8601 date (yyyy-mm-dd) when the AIP was last revised.
    • scope: The scope for the AIP. This must match the directory name for that scope. Required for AIPs with IDs >= 1000, prohibited otherwise.
  • The permalink key (required): This must be set to /{aip.scope}/{aip.id}. If there is no scope, use /{aip.id} instead.
  • The redirect_from key: This should include a list of any /{aip.id} permutations that a reader would be likely to enter, including:
    • /{aip.id} (for AIPs where the permalink includes the scope)
    • AIP IDs with zero-padding, for each level of zero-padding up to four digits (for example: /08, /008, /0008).

Document structure

AIPs must begin with a top-level heading with the AIP's title (# Title). The title should be a noun (not an imperative). For example, "Bad API precedents" not "Avoid breaking API precedent".

AIPs should then begin with an introduction (with no additional heading), followed by a ## Guidance heading. If necessary, the AIP may include any of the following after the guidance, in the following order:

  • "Further reading" is a bulleted list of links to other AIPs that are useful to fully understand the current AIP.
  • "Appendices" covering further explanation in the same AIP. These are relatively rare but are important in cases where an AIP requires a lot of justification for the decision. Often this is primarily an explanation of alternatives considered to help explain the guidance.
  • "Changelog" is a bulleted list of changes made to the AIP since the first writing.

The guidance section may include subsections that elaborate further on details. Subsections will automatically create an entry in the table of contents, and an anchor for citations.

Below is an example AIP shell that uses each major section:

# AIP title

The introductory text explains the background and reason why the AIP exists. It
lays out the basic question, but does not tell the reader what to do.

## Guidance

The "guidance" section helps the reader know what to do. A common format for
the guidance section is a high-level imperative, followed by an example,
followed by a bulleted list explaining the example.

### Subsection

Individual subsections can be cited individually, and further elaborate
details.

## Rationale

The "rationale" section is optional, and helps the reader understand the
motivation behind specific guidance within the AIP.

Deeper explanations of design justification and tradeoffs **must** be in the
rationale instead of other sections, to ensure the rest of the document acts as
an easily actionable reference.

## History

The "history" section is optional, and documents events and context around a
significant edit to an AIP. For example, explanation of rewrite would be
included in this section

While the changelog is a dotted list of one-line summaries of changes to an AIP,
the history section should elaborate on significant events in a descriptive
format.

The section **must not** be used to exhaustively enumerate all changes. This
is what the changelog provides.

## Further reading

A bulleted list of (usually) other AIPs, in the following format:

- [AIP-1](/1): AIP purpose and guidelines

## Changelog

A bulleted list of changes in reverse chronological order, using the following
format:

- **2020-02-18**: Specified ordering.
- **2019-07-01**: Added a subsection clarifying XYZ.

AIPs should attempt to follow this overall format if possible, but AIPs may deviate from it if necessary (in particular, if the AIP would be more difficult to understand, even for a reader already accustomed to reading AIPs in the usual format).

Note: Except for the title, AIPs must only use the second heading level (##) and above. AIPs should only use the second and third heading levels (##, ###).

Requirement keywords

AIPs should use the following requirement level keywords: "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted as described in RFC 2119.

When using these terms in AIPs, they must be lower-case and bold. These terms should not be used in other ways.

If "SHOULD" or "SHOULD NOT" are used, they must include valid examples of where other concerns may override the guidance.

Important: If rationale is used, it exists to provide background and a more complete understanding, but must not contain guidance (and RFC-2119 terms must not be used).

Code examples

API design examples in AIPs should use protocol buffers. Examples should cover only enough syntax to explain the concept. When using RPCs in examples, a google.api.http annotation should be included.

Referencing AIPs

When AIPs reference other AIPs, the prosaic text must use the format AIP-XXXX without zero-padding (e.g., [AIP-8](/8), not AIP-0008), and must link to the relevant AIP. AIP links may point to a particular section of the AIP if appropriate.

Important: AIP links must use the relative path to the file in the repository (such as /8 for core AIPs, or /8 for AIPs in a subdirectory); this ensures that the link works both on the AIP site, when viewing the Markdown file on GitHub, using the local development server, or a branch.

Rationale

Designing for a broad set of clients

API guidance, similar to any software, is most beneficial when there is a clear purpose and target beneficiary.

The beneficiaries of improved API design are users. These users interact with APIs via a variety of clients, depending on their use case as enumerated above.

API guidance must in turn consider the impact broadly across these clients.

Changelog

  • 2023-05-20: Increase API guidance scope to include broad set of clients.
  • 2023-03-30: Removed appendix, added rationale and history to the template.
  • 2020-02-18: Specified reverse chronological ordering for changelog items.
  • 2019-08-23: Added guidance for internal AIP links.