[ADP-3] ADP Numbering

Purpose

The purpose of the ADP number is to facilitate referencing (e.g., "according to ADP-501, ..."). Additionally, to facilitate management, we have established some rules to categorize related ADPs into specific subject directories, each retaining a range of numbers.

Guidance

• Each ADP MUST have a unique identifier, currently a number.
• General ADPs MAY define their own ADP number range within the assigned range.
• ADP numbers MUST follow the allocation below:

ADP Number Allocation

• 0-1000: Reserved for general ADPs related to HTTP API design.
  • This directory is currently further divided into several different subdirectories.
    • ADP General: 0-19
    • Engineering Principles: 20-39
    • API Governance: 40-79
    • Naming Conventions: 80-99
    • HTTP Basics: 100-299
    • REST Basics: 300-350
    • HTTP Semantics: 350-399
    • Error Design: 400-599
    • Event Design: 600-699
    • JSON Principles: 700-749
    • OpenAPI Principles: 750-799
• 1000-2000: Reserved for extensions or supplements to the general ADPs in the 0-1000 range.
• 2000-2499: Reserved for WebSocket API design.
• 2500-2999: Reserved for GraphQL API design.
• 3000-3999: Reserved for asynchronous API design.
• 4000-4999: Reserved for non-HTTP-based API design.
• 10000+, 20000+, 30000+, etc.: Reserved for specific applications/languages/components/libraries specific ADPs.

DRAFT Status and Version Control

• Each ADP should (SHOULD) include a status field indicating its current status:

  • draft: Initial proposal
  • reviewing: Under review
  • published: Approved for implementation
  • deprecated: No longer recommended

• DRAFT ADPs that have already been published should (SHOULD) also include a Changelog to track changes over time.

Examples

• ADP-404: HTTP API Error Handling (General, HTTP API Design)
• ADP-2105: WebSocket Connection Lifecycle (WebSocket API Design)
• ADP-2750: GraphQL Query Complexity Limitation (GraphQL API Design)
• ADP-10042: MyApp Specific Error Handling (Application Specific ADP)

Handling Overlaps

• In cases where an ADP may fit multiple categories (e.g., a GraphQL API using WebSocket), it should (SHOULD) use the most specific or primary category. If necessary, cross-references to related ADPs in other categories can be included.

Future Expansion

The ADP numbering system may expand in the future to accommodate new categories or subcategories. Any such expansions will be announced and documented in updates to this ADP.