AEP Style and Guidance

AEP stands for API Enhancement 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 and the way API teams discuss and come to consensus on API guidance.

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

Guidance

• AEPs must cover a single, discrete topic, and provide clear, actionable guidance.
• AEPs must not duplicate or contradict guidance in another AEP.
• AEPs may also cover what not to do, but should not cover only anti-patterns.
• If AEP 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 AEP 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.
• Declarative 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 enhancements include:

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

AEP 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 enhancements in readability (e.g. rename expire_time to lapse_time since lapse is a common term in my service).

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

File structure

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

AEPs must have appropriate front matter.

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

Front matter for AEPs must include:

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

Document structure

AEPs must begin with a top-level heading with the AEP’s title (# Title). The title should be a noun (not an imperative). For example, “Bad API precedents” not “Avoid breaking API precedent”.

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

• “Further reading” is a bulleted list of links to other AEPs that are useful to fully understand the current AEP.
• “Appendices” covering further explanation in the same AEP. These are relatively rare but are important in cases where an AEP 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 AEP 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 AEP shell that uses each major section:

# AEP title

The introductory text explains the background and reason why the AEP 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 AEP.

Deeper explanations of design justification and tradeoffs <b class="font-extrabold  text-red-700">must</b> 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 AEP. 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
AEP, the history section should elaborate on significant events in a
descriptive format.

The section <b class="font-extrabold  text-red-700">must not</b> be used to exhaustively enumerate all changes. This is
what the changelog provides.

## Further reading

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

- [AEP-1](./0001.md): AEP 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.

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

Note

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

Requirement keywords

AEPs 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 AEPs, 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 AEPs should be presented in both OpenAPI and 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.

AEPs should use snake-case naming for parameters and properties (fields), for consistency across OpenAPI and protocol buffers, but other casing conventions may be used as long as they are applied uniformly.

Referencing AEPs

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

Important

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

Error codes

When referencing a error code, the prose should use the format {google.api.error_code} / {http_status_code}. For example, OK / 200.

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

• 2024-03-02: From from https://google.aip.dev/8