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

1. Identify the Requirement: e.g., "I need to add a 'status' field."
2. Find the Rule: Search the index above. "AEP-216: States" looks relevant.
3. 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
4. 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