aep

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

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