api-design

API Design

Mandatory API gates are owned by the API rule (${HANDBOOK_ROOT}/rules/320-api-design.mdc). This skill owns design workflow, trade-offs, examples, and protocol-specific guidance.

Non-Negotiables

• Design from consumers, business invariants, trust boundaries, and failure behavior before choosing endpoint shapes.
• Let resource identifiers name nouns and protocol operations express behavior. Model a business action as a subordinate resource when that produces a clear lifecycle.
• Follow HTTP safety, idempotency, cache, conditional-request, and status-code semantics. Idempotence means the intended server effect is stable, not that every response is byte-identical.
• Authenticate the principal and authorize every protected object, tenant, relationship, field, and action on the server.
• Validate and bound every path, query, header, cookie, message, and body input. Serialize responses from allowlisted schemas rather than persistence objects.
• Use RFC 9457 Problem Details for new public HTTP error contracts unless an existing compatibility commitment requires another documented shape.
• Make retryable mutations safe with a stable operation identity, atomic state, and reconciliation. Never imply that transport delivery proves exactly-once business processing.
• Protect mutable resources from lost updates when concurrency matters.
• Treat the API description as a versioned contract. Detect breaking changes, provide migration evidence, and deprecate deliberately.
• Bound payloads, pagination, batches, queries, streams, execution time, concurrency, retries, queues, and per-principal cost.
• Keep secrets, credentials, raw payloads, and unnecessary personal data out of errors and telemetry.

Design Workflow

1. Define Consumers and Guarantees

Document:

• consumers, trust levels, environments, and ownership;
• critical operations and business invariants;
• latency, availability, durability, freshness, and consistency needs;
• authentication mechanism and authorization policy inputs;
• expected load, object size, request size, page size, concurrency, and growth;
• retry, duplicate, ordering, and partial-failure behavior;
• compatibility window, support policy, and deprecation owner.