AEP Numbering and Organization

This document describes the numbering system and general organization of AEPs.

AEP numbers:

• Are unique. No two AEPs share the same number.
• Indicate the order in which they are authored.

To help with organization and discovery, AEPs also have a category and a slug to easily discover and refer to the AEP.

See below for an example of an AEP id, category, and slug, expressed via YAML front-matter:

id: 11
category: 'resources'
slug: 'create'

AEP Numbers

Core AEPs

To uniquely identify an AEP, each one is assigned a permanent number as it is merged.

• A merged AEP must use the next available number.
• AEPs must be numbered between 1 and 9999.

AEP Blocks

While AEP numbers are generally assigned sequentially, specific blocks are reserved to group AEPs by their primary function. This helps users distinguish between administrative processes, educational materials, and technical standards.

The currently recognized blocks are:

• 1–49: Meta, general, and process AEPs.
• 50–99: Educational/fundamental AEPs. They provide the conceptual foundation required to understand and apply API design standards.
• 100–999: API design guidance AEPs. They define technical standards and requirements for APIs within the organization.

AEP Categories

To help with discovery of an AEP, each one is assigned a category: a string that describes a theme or grouping the AEP belongs in.

• The category of an AEP may change over time.

As an example, the guidance around custom methods may grow to multiple AEPs. As such, AEPs may create a new category “custom-methods” and recategorize relevant AEPs (mutating custom methods, retrieval custom methods) under it.

Categories are expressed in the YAML front-matter of an AEP:

category: 'custom-methods'

AEP Slugs

Each AEP is given a slug: a string by which it can be easily referenced and accessible via a URL on the AEP site.

• The slug of an AEP may change over time, sometimes to refer to a new revision of an existing AEP.
• On the AEP site, the AEP is then available by with a path of the slug: /{slug}.

For example, an AEP-123 may author guidance around a design pattern for revisions of resources and be given the slug “revisions”. If a new AEP-1340 that provides a significant change is authored, then it may use the slug “revisions”, with AEP-123 given a slug like “revisions-deprecated”.

Slugs are expressed in the YAML front-matter of an AEP:

slug: 'create'

And is available via the path /create on the site.

Rationale

Why AEP Slugs

In the original aip.dev project, numbers were the primary identifier for an AEP. However, as a number does not hint to its purpose or the guidance it contains, conversations around AIPs were difficult to hold and often the AIPs would be referred to by an unofficial colloquial name rather than by its number.

As such, AEPs provide the ability for a semantic slug.

Why AEP Categories

With aip.dev, numbers were an organizational scheme, with AIPs sorted by number in navigation. Using numbers resulted in difficulties putting a new AEP alongside related AEPs if a number was not available.

By adding categories, new AEPs can easily be organized, as well as produce more granular categories as the need arises.

Changelog

• 2026-01-20: Add section on AEP blocks, and which ones are reserved.
• 2025-10-30: Initial AEP-2 for Thryv, adapted from Google AIP-2 and aep.dev AEP-2.