| name | aep |
| description | AEP (API Enhancement Proposals) design standards. Use when designing, reviewing, or implementing APIs to ensure compliance with AEP conventions. |
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
