API and Interface Design
Design the contract from the caller's failure modes, not only the happy path.
Establish the contract
- Identify consumers, trust boundaries, lifecycle, latency expectations, and
ownership.
- Define request/command shape, response/event shape, status or error model,
validation, defaults, and canonical examples.
- Decide idempotency, retries, ordering, pagination, concurrency, rate limits,
cancellation, and partial failure behavior.
- Define authentication, authorization, sensitive fields, and audit needs.
- Decide compatibility and versioning: additive change, migration, deprecation,
or explicit breaking release.
Read contract-checklist.md for the review
matrix. Keep the contract close to the owning schema or source of truth and
generate clients/docs only when the repository already supports generation.
Implementation handoff
Write examples that can become contract tests. Include malformed input,
missing resource, duplicate request, timeout, dependency failure, permission
denial, and oversized input cases. Make error codes stable enough for callers
and messages safe enough for logs and users.
Do not expose internal stack traces, persistence identifiers, or implementation
details by accident. Do not add versioning machinery before a compatibility
need exists.
Completion condition
Consumers can predict valid requests, successful and failed responses, retry
behavior, compatibility impact, and the evidence that proves the boundary.
1---2name: api-and-interface-design3description: Designs or reviews HTTP, REST, GraphQL, RPC, CLI, webhook, event, and service interfaces with explicit inputs, outputs, errors, compatibility, idempotency, pagination, authentication, versioning, and observability. Use when introducing or changing an API or cross-component contract. Not for internal implementation details with no boundary or for debugging one API failure; use root-cause-debugging there.4---56# API and Interface Design78Design the contract from the caller's failure modes, not only the happy path.910## Establish the contract11121. Identify consumers, trust boundaries, lifecycle, latency expectations, and13 ownership.142. Define request/command shape, response/event shape, status or error model,15 validation, defaults, and canonical examples.163. Decide idempotency, retries, ordering, pagination, concurrency, rate limits,17 cancellation, and partial failure behavior.184. Define authentication, authorization, sensitive fields, and audit needs.195. Decide compatibility and versioning: additive change, migration, deprecation,20 or explicit breaking release.2122Read [contract-checklist.md](references/contract-checklist.md) for the review23matrix. Keep the contract close to the owning schema or source of truth and24generate clients/docs only when the repository already supports generation.2526## Implementation handoff2728Write examples that can become contract tests. Include malformed input,29missing resource, duplicate request, timeout, dependency failure, permission30denial, and oversized input cases. Make error codes stable enough for callers31and messages safe enough for logs and users.3233Do not expose internal stack traces, persistence identifiers, or implementation34details by accident. Do not add versioning machinery before a compatibility35need exists.3637## Completion condition3839Consumers can predict valid requests, successful and failed responses, retry40behavior, compatibility impact, and the evidence that proves the boundary.
thiientv