• File Bug
• View source
• Edit this page

AIP-8

AIP Style and Guidance

AIP stands forAPI Improvement Proposal, which is a design documentproviding high-level, concise documentation for API design and development. Thegoal is for these documents to serve as the source of truth for API-relateddocumentation at Google and the way API teams discuss and come to consensus onAPI guidance.

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

Guidance

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

Guidance contained within an AIPmust be beneficial to one or moretypes 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. requiringsingular andplural on agoogle.api.resource annotation).

AIP guidancemust not be a significant detriment to a client's usability orimplementation 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 thisexcept for resources that start with the name Foo).
• Renames of well-established fields for minor improvements in readability (e.g. renameexpire_time tolapse_time sincelapse is a common term in my service).

While the length of AIPs will necessarily vary based on the complexity of thequestion, most AIPsshould be able to cover their content in roughly twoprinted pages.

File structure

AIPsmust be written in Markdown, andmust be named using theirfour-digit number (example:0008.md). AIPs that serve a specific scopemust be in the subdirectory for that scope.

AIPsmust have appropriate front matter.

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

Front matter for AIPsmust include:

• Theaip 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 inAIP-1, and common states aredraft,reviewing, andapproved.
  • 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. Thismust match the directory name for that scope. Required for AIPs with IDs >= 1000, prohibited otherwise.
• Thepermalink key (required): Thismust be set to/{aip.scope}/{aip.id}. If there is no scope, use/{aip.id} instead.
• Theredirect_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

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

AIPsshould then begin with an introduction (with no additional heading),followed by a## Guidance heading. If necessary, the AIPmay include anyof 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 sectionmay include subsections that elaborate further ondetails. Subsections will automatically create an entry in the table ofcontents, and an anchor for citations.

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

# AIP titleThe introductory text explains the background and reason why the AIP exists. Itlays out the basic question, but does not tell the reader what to do.## GuidanceThe "guidance" section helps the reader know what to do. A common format forthe guidance section is a high-level imperative, followed by an example,followed by a bulleted list explaining the example.### SubsectionIndividual subsections can be cited individually, and further elaboratedetails.## RationaleThe "rationale" section is optional, and helps the reader understand themotivation behind specific guidance within the AIP.Deeper explanations of design justification and tradeoffs**must** be in therationale instead of other sections, to ensure the rest of the document acts asan easily actionable reference.## HistoryThe "history" section is optional, and documents events and context around asignificant edit to an AIP. For example, explanation of rewrite would beincluded in this sectionWhile 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 descriptiveformat.The section**must not** be used to exhaustively enumerate all changes. Thisis what the changelog provides.## Further readingA bulleted list of (usually) other AIPs, in the following format:- [AIP-1](/1): AIP purpose and guidelines## ChangelogA bulleted list of changes in reverse chronological order, using the followingformat:-**2020-02-18**: Specified ordering.-**2019-07-01**: Added a subsection clarifying XYZ.

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

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

Requirement keywords

AIPsshould use the following requirement level keywords: "MUST", "MUSTNOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted asdescribed inRFC 2119.

When using these terms in AIPs, theymust be lower-case andbold. Thesetermsshould not be used in other ways.

If "SHOULD" or "SHOULD NOT" are used, theymust include valid examples ofwhere other concerns may override the guidance.

Important: If rationale is used, it exists to provide background and a morecomplete understanding, butmust not contain guidance (and RFC-2119 termsmust not be used).

Code examples

API design examples in AIPsshould useprotocol buffers. Examplesshould cover only enough syntax to explain the concept. When using RPCs inexamples, agoogle.api.http annotationshould be included.

Referencing AIPs

When AIPs reference other AIPs, the prosaic textmust use the formatAIP-XXXX without zero-padding (e.g.,[AIP-8](/8), notAIP-0008), andmustlink to the relevant AIP. AIP linksmay point to a particular section of theAIP if appropriate.

Important: AIP linksmust use the relative path to the file in therepository (such as/8 for core AIPs, or/8 for AIPs in asubdirectory); this ensures that the link works both on the AIP site, whenviewing the Markdown file on GitHub, using the local development server, or abranch.

Rationale

Designing for a broad set of clients

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

The beneficiaries of improved API design are users. These users interact withAPIs 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.