AEP (API Enhancement Proposals) Skill
Overview
AEPs (API Enhancement Proposals) are the authoritative design standards for APIs. They ensure consistency, intuitiveness, and long-term stability across all services.
Rule of Thumb: AEPs are numbered by importance. Lower numbers are more fundamental.
- < 100: Meta-policies and governance.
- 100-199: CORE STANDARDS. Every API developer must know these.
- 200+: Specific patterns and edge cases.
AEP Index
📌 Core Resource Design (Start Here)
Defines the fundamental shape of the API.
- AEP-121: Resource-oriented design (The data model: Resources vs Collections)
- AEP-122: Resource names (URL structure, formatting)
- AEP-124: Resource association (Relationships between resources)
- AEP-101: OpenAPI (Specification standards)
- AEP-102: APIs and API terminology
- AEP-126: Enumerations
- AEP-127: HTTP and gRPC Transcoding
🛠️ Standard Methods (The "CRUD")
Every resource should support these standard interactions unless impossible.
- AEP-130: Methods (General guidance)
- AEP-131: Get (Retrieving a single resource)
- AEP-132: List (Listing collections, includes pagination)
- AEP-133: Create (Creating new resources)
- AEP-134: Update (Updating resources,
update_mask)
- AEP-135: Delete (Deleting resources)
⚡ Advanced Methods
- AEP-136: Custom methods (Verbs beyond CRUD, e.g.,
Cancel, Undelete)
- AEP-137: Apply (Declarative configuration updates)
📋 Fields & Data Types
Naming conventions and data formats.
- AEP-140: Field names (Snake_case, reserved words)
- AEP-141: Quantities (Units, measurements)
- AEP-142: Time and duration (Timestamp formats)
- AEP-143: Standardized codes (IETF/ISO standards)
- AEP-144: Array fields (Repeated fields)
- AEP-145: Ranges (Start/end intervals)
- AEP-146: Generic fields (Any, Struct)
- AEP-148: Standard fields (
name, create_time, update_time, display_name)
🧩 Common Patterns & Features
- AEP-158: Pagination (Page tokens, page size)
- AEP-151: Long-running operations (Async tasks)
- AEP-193: Errors (Status codes, error details)
- AEP-154: Preconditions (ETags, concurrency)
- AEP-155: Idempotency (Request IDs)
- AEP-156: Singleton resources (Config, Settings)
- AEP-157: Partial responses (Field selection)
- AEP-159: Reading across collections ("List all books in all libraries")
- AEP-160: Filtering (Filter syntax)
- AEP-161: Field masks (Partial updates)
- AEP-162: Resource Revisions
- AEP-164: Soft delete
📚 Documentation & Compatibility
- AEP-180: Protobuf Backwards compatibility
- AEP-191: File and directory structure
- AEP-192: Documentation (Comments, formatting)
🔍 Specific Patterns (200+)
- AEP-203: Field behavior documentation (Required, Output Only)
- AEP-210: Unicode
- AEP-211: Authorization checks
- AEP-213: Common components
- AEP-214: Resource expiration (TTL)
- AEP-216: States (Enums for lifecycle)
- AEP-217: Unreachable resources
📦 Batch Operations
Essential for high-volume agent operations.
- AEP-231: Batch Get
- AEP-233: Batch Create
- AEP-234: Batch Update
- AEP-235: Batch Delete
Pro Tip: Partial Success for Agents
When building APIs for agents, prefer partial success semantics over all-or-nothing atomicity, even for synchronous batch operations. This allows agents to succeed on valid operations and receive specific error details for failed ones, preventing a single invalid entry from blocking an entire batch. Use a failed_requests map to return individual errors.
🏛️ Meta & Governance
- AEP-1: Purpose and Guidelines
- AEP-5: Designing an API (The process)
- AEP-300: AEP Editions
How to Use
- Identify the Requirement: e.g., "I need to add a 'status' field."
- Find the Rule: Search the index above. "AEP-216: States" looks relevant.
- Read the Standard:
- The content is located in:
references/aep/general/<NUMBER>.md
- Example: To read about Standard Fields, check
references/aep/general/0148.md
- Verify: Ensure your implementation matches the spec exactly (naming, behavior, types).
Pro Tip: Use grep to search across all AEPs if the index isn't enough:
grep -r "my search term" references/aep/general
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: aep3description: API design system in the AEP (API Enhancement Proposals) collection. AEPs provide high-level, concise documentation for API development, serving as the source of truth for consistent, intuitive, and machine-readable API designs. Use this skill when designing, reviewing, or implementing APIs to ensure compliance with these established standards. Use when this capability is needed.4---56# AEP (API Enhancement Proposals) Skill78## Overview910AEPs (API Enhancement Proposals) are the authoritative design standards for APIs. They ensure consistency, intuitiveness, and long-term stability across all services.1112**Rule of Thumb:** AEPs are numbered by importance. **Lower numbers are more fundamental.**13- **< 100:** Meta-policies and governance.14- **100-199:** **CORE STANDARDS.** Every API developer must know these.15- **200+:** Specific patterns and edge cases.1617## AEP Index1819### 📌 Core Resource Design (Start Here)20*Defines the fundamental shape of the API.*21- **AEP-121:** Resource-oriented design (The data model: Resources vs Collections)22- **AEP-122:** Resource names (URL structure, formatting)23- **AEP-124:** Resource association (Relationships between resources)24- **AEP-101:** OpenAPI (Specification standards)25- **AEP-102:** APIs and API terminology26- **AEP-126:** Enumerations27- **AEP-127:** HTTP and gRPC Transcoding2829### 🛠️ Standard Methods (The "CRUD")30*Every resource should support these standard interactions unless impossible.*31- **AEP-130:** Methods (General guidance)32- **AEP-131:** **Get** (Retrieving a single resource)33- **AEP-132:** **List** (Listing collections, includes pagination)34- **AEP-133:** **Create** (Creating new resources)35- **AEP-134:** **Update** (Updating resources, `update_mask`)36- **AEP-135:** **Delete** (Deleting resources)3738### ⚡ Advanced Methods39- **AEP-136:** Custom methods (Verbs beyond CRUD, e.g., `Cancel`, `Undelete`)40- **AEP-137:** Apply (Declarative configuration updates)4142### 📋 Fields & Data Types43*Naming conventions and data formats.*44- **AEP-140:** Field names (Snake_case, reserved words)45- **AEP-141:** Quantities (Units, measurements)46- **AEP-142:** Time and duration (Timestamp formats)47- **AEP-143:** Standardized codes (IETF/ISO standards)48- **AEP-144:** Array fields (Repeated fields)49- **AEP-145:** Ranges (Start/end intervals)50- **AEP-146:** Generic fields (Any, Struct)51- **AEP-148:** Standard fields (`name`, `create_time`, `update_time`, `display_name`)5253### 🧩 Common Patterns & Features54- **AEP-158:** **Pagination** (Page tokens, page size)55- **AEP-151:** Long-running operations (Async tasks)56- **AEP-193:** **Errors** (Status codes, error details)57- **AEP-154:** Preconditions (ETags, concurrency)58- **AEP-155:** Idempotency (Request IDs)59- **AEP-156:** Singleton resources (Config, Settings)60- **AEP-157:** Partial responses (Field selection)61- **AEP-159:** Reading across collections ("List all books in all libraries")62- **AEP-160:** Filtering (Filter syntax)63- **AEP-161:** Field masks (Partial updates)64- **AEP-162:** Resource Revisions65- **AEP-164:** Soft delete6667### 📚 Documentation & Compatibility68- **AEP-180:** Protobuf Backwards compatibility69- **AEP-191:** File and directory structure70- **AEP-192:** Documentation (Comments, formatting)7172### 🔍 Specific Patterns (200+)73- **AEP-203:** Field behavior documentation (Required, Output Only)74- **AEP-210:** Unicode75- **AEP-211:** Authorization checks76- **AEP-213:** Common components77- **AEP-214:** Resource expiration (TTL)78- **AEP-216:** States (Enums for lifecycle)79- **AEP-217:** Unreachable resources8081### 📦 Batch Operations82*Essential for high-volume agent operations.*83- **AEP-231:** Batch Get84- **AEP-233:** Batch Create85- **AEP-234:** Batch Update86- **AEP-235:** Batch Delete8788> **Pro Tip: Partial Success for Agents**89> When building APIs for agents, prefer **partial success** semantics over all-or-nothing atomicity, even for synchronous batch operations. This allows agents to succeed on valid operations and receive specific error details for failed ones, preventing a single invalid entry from blocking an entire batch. Use a `failed_requests` map to return individual errors.9091### 🏛️ Meta & Governance92- **AEP-1:** Purpose and Guidelines93- **AEP-5:** Designing an API (The process)94- **AEP-300:** AEP Editions9596## How to Use97981. **Identify the Requirement:** e.g., "I need to add a 'status' field."992. **Find the Rule:** Search the index above. "AEP-216: States" looks relevant.1003. **Read the Standard:**101 - The content is located in: `references/aep/general/<NUMBER>.md`102 - *Example:* To read about Standard Fields, check `references/aep/general/0148.md`1034. **Verify:** Ensure your implementation matches the spec exactly (naming, behavior, types).104105**Pro Tip:** Use `grep` to search across all AEPs if the index isn't enough:106`grep -r "my search term" references/aep/general`107108---109> Converted and distributed by [TomeVault](https://tomevault.io/claim/way-platform) — claim your Tome and manage your conversions.110<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io