api-and-interface-design

# API and Interface Design Design the contract from the caller's failure modes, not only the happy path. ## Establish the contract 1. Identify consumers, trust boundaries, lifecycle, latency expectations, and ownership. 2. Define request/command shape, response/event shape, status or error model, validation, defaults, and canonical examples. 3. Decide idempotency, retries, ordering, pagination, concurrency, rate limits, cancellation, and partial failure behavior. 4. Define authentication, authorization, sensitive fields, and audit needs. 5. Decide compatibility and versioning: additive change, migration, deprecation, or explicit breaking release. Read [contract-checklist.md](references/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 im...