diff --git a/aep/general/0002/aep.md b/aep/general/0002/aep.md index a7a7709c..d7d8d7a6 100644 --- a/aep/general/0002/aep.md +++ b/aep/general/0002/aep.md @@ -1,36 +1,61 @@ -# AEP Numbering +# AEP Numbering and Organization -This document describes the numbering system. +This document describes the numbering system and general organization of AEPs. -AEP provides a numbering system that: +AEP numbers: -- Groups AEPs primarily by their purpose, and secondarily by the general theme - they are discussing. -- Allows for new AEPs to be added incrementally, without adjusting the numbers - of existing AEPs. +- Are unique. No two AEPs share the same number. +- Indicate the order in which they are authored. -## AEP Blocks +To help with organization and discovery, AEPs also have a category and a slug +to easily discovery and refer to the AEP. -The list of blocks are: +## AEP Numbers -| Range | Name | Description | -| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1-999 | meta topics | topics that are not directly related to API guidance, but provide guidance or clarity for the AEPs themselves | -| 1000-1999 | specification | APIs which are AEP-compliant **must** adhere to these AEPs. Clients authors may read these AEPs to determine what behavior they can rely on when integrating with AEP-compliant APIs. | -| 2000-2999 | design patterns | Best practice design patterns for common API use cases. API authors should read these AEPs to help with the design of their APIs. | -| 3000-9999 | reserved | Reserved for future use by the AEP project. | +### Core AEPs -## Organization-specific AEPs +To uniquely identify an AEP, each one is assigned a permanent number once it +has been merged into the aep.dev repository. The AEP number assigned **must** +be the next available number. AEPs **must** be numbered between 1 and 9999. + +### Organization-specific AEPs Organizations **may** extend the AEPs with guidance that is relevant to them. -When doing so, they **must** use the AEP range 10000-11000. +When doing so, they **must** use AEP numbers 10000 or greater. + +## AEP Categories + +To help with discovery of an AEP, each one is assigned a category: a string the +describes a theme or grouping the proposal belongs in. The category of a +proposal **may** change over time. + +## AEP Slugs + +Each AEP is given a slug: a string by which it can be easily referred to. The +slug of an AEP **may** change over time, sometimes to refer to a new revision +of an existing AEP. ## Rationale -Providing well delineated AEP blocks helps guide users of the AEPs to the -specific sections that are relevant to them. Providing blocks of 1000 ensures -that are a sufficient number to ensure that any future guidance may be easily -added. +### Why AEP Slugs + +In the original aip.dev project, numbers were the primary identifier for a +proposal. 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 +were 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 new proposals +alongside related proposals if a number was not available. + +By adding categories, AEPs can easily organize new proposals, as well as +produce more granular categories as the need arises. + +### Why Organization-specific AEPs Similar to [google.aip.dev](google.aip.dev), the organizations supporting the AEP project found the need for providing organization-specific guidance that is diff --git a/aep/general/0151/lro.oas.yaml b/aep/general/0151/lro.oas.yaml index ed53e3b6..18fc61d4 100644 --- a/aep/general/0151/lro.oas.yaml +++ b/aep/general/0151/lro.oas.yaml @@ -22,15 +22,12 @@ components: properties: name: type: string - description: - The server-assigned name, which is only unique within the same - service that originally returns it. + description: The server-assigned name, which is only unique within the same service that originally returns it. done: type: boolean description: >- - If the value is false, it means the operation is still in progress. - If true, the operation is completed, and either response or error - is available. + If the value is false, it means the operation is still in progress. If true, the operation is completed, + and either response or error is available. error: $ref: '#/components/schemas/Error' required: