AEP-Compliant API Design

Design APIs following AEP (Google, Microsoft, Roblox, IBM). The payoff: Terraform providers, CLIs, UIs, and MCP servers auto-generate because they can predict the API shape from resource hierarchies.

Core principle: design resource hierarchies (nouns), not procedure collections (verbs).

Designing around caller intent

Design the API surface around what callers actually want, expressed in their vocabulary — not around how the implementation is structured internally. A networking API should expose connect, read_message, write_message, and disconnect. Exposing a "socket" instead leaks a Unix implementation concept that bundles unrelated concerns (files, network, device I/O) into a single abstraction callers never asked for. The right question is: what does the caller need to accomplish, and what are the fewest, most coherent calls that let them do it?

No footgun-by-omission. Nothing should fail silently because the caller forgot to set an obscure flag or initialize an optional field. Mandatory low-level knobs are a design smell; sensible, safe behavior should be the default, with explicit opt-in for deviation.

Separate the escape hatch. Provide raw or low-level bindings as a distinct layer for the rare callers who genuinely need them. The common-case API should not force everyone through low-level machinery. (See software-design's "layered interfaces" for the structural pattern.)

Difficulty is not a virtue. Jonathan Blow argues — with OpenGL and Vulkan as examples — that keeping a hard API because you feel pride in having mastered it is not a design principle; it is a cost imposed on every future caller. Complexity is only justified when it is essential to the problem domain, which is rare.

Design Process

For every API, answer these four questions in order:

1. What are the resources (things)?
2. What's the parent-child hierarchy?
3. What does each resource's schema look like?
4. Which standard methods does each resource need?

Before (verb-oriented — hard to auto-generate clients):

POST /v1/createProject
POST /v1/archiveProject
POST /v1/getProjectTasks

After (resource-oriented — predictable, tooling-friendly):

POST   /v1/projects                       # Create
GET    /v1/projects/{project_id}          # Get
GET    /v1/projects                       # List
PATCH  /v1/projects/{project_id}          # Update
DELETE /v1/projects/{project_id}          # Delete
POST   /v1/projects/{project_id}:archive  # Custom method (state transition)
GET    /v1/projects/{project_id}/tasks    # Nested collection

Model a resource hierarchy, not a database schema — the API is a contract, not a DB mirror. Resource relationships must form a DAG (no cycles).

Standard Methods (AEP-130–135)

Prefer standard > batch > custom > streaming. Each step down costs tooling compatibility.

OperationId naming: {Verb}{Singular} for standard (GetBook, CreateBook), List{Plural} for List (ListBooks).

Conventions That Diverge From Common Practice

These AEP rules are the ones most likely to be missed. Each exists for a specific reason:

• results array in List responses — not books or users. A consistent name lets generic clients parse any collection without knowing the resource type.
• id as query param on Create — POST /v1/tasks?id=my-task. Keeps the body a clean resource representation. Without user-specified IDs, Create isn't safely retryable and declarative clients (Terraform) can't reconcile state.
• PATCH + merge-patch, never PUT — PUT requires the full resource, so adding a new schema field silently becomes breaking (old clients reset it to zero value on every update).
• _time suffix on timestamps — create_time, update_time. Never _at, never camelCase. This makes timestamps recognizable across all AEP APIs.
• Permissions before existence — always check auth first (-> 403), then existence (-> 404). Reversing this leaks which resources exist to unauthorized callers.
• RFC 9457 errors — Content-Type: application/problem+json with type, status, title, detail. Dynamic variables in detail must also appear as top-level fields for programmatic access.
• State transitions via custom methods — :archive, :publish, not PATCH on a state field. State machines need server-side validation that Update can't express.
• Duplicate Create ID -> 409 ALREADY_EXISTS, unless caller can't see the duplicate -> 403 (avoids leaking existence info).

Review Checklist

• Resources use nouns, not verbs; hierarchy forms a DAG
• List response array is results
• Create supports user-specified id as query param
• Update uses PATCH + merge-patch, not PUT
• Timestamps use _time suffix, RFC 3339 format
• Pagination on all List methods from day one
• Permissions checked before existence
• Errors use application/problem+json (RFC 9457)
• State transitions use custom methods, not Update
• Delete with children requires force: bool
• create_time, update_time, etag on mutable resources
• path field is output-only on every resource
• Long-running operations (LROs) return 202 Accepted with Operation resource
• Does the surface expose caller intent, or leak an internal implementation concept?
• When the API accepts raw input, does conversion raise on invalid data rather than silently accepting it? (parse, don't validate — see software-design/references/type-driven-design.md)
• Does every method name accurately describe ALL of what it does, including side effects? (Least Astonishment)
• Do consistent name patterns signal consistent behavior across the surface? (delete_* always deletes, never soft-deletes sometimes)
• Are defaults safe? (fail closed, return empty collection not null, require explicit opt-in for dangerous behavior)

References