AIP-8

AIP Style guide

AIP stands for API Improvement Proposal, which is a design document providing high-level, concise documentation for API 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 should fundamentally answer the question, "What do I do?" with actionable guidance. AIPs may also cover what not to do, but should not cover only anti-patterns.

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.

---
aip:
  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.

Important: If an appendix 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.

Changelog

  • 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.