Documentation
README
API Design And Evolution
Design an interface as a durable agreement with its consumers, not a route list. Start with the consumer job, domain meaning, authority boundary, and failure modes; then choose the interface style and contract format. Keep facts, assumptions, and policy decisions distinguishable.
When To Use
Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or message contract, webhook, or streaming interface. Use it before implementation and again whenever consumer-visible behavior changes.
Do not use this as an ADR template, a complete product-discovery method, a security assessment, or an implementation test plan. Hand those concerns to adr-authoring, product-discovery, secure-software-engineering, and verification-methodology, respectively.
Workflow
- Discover the agreement. State consumer jobs, domain terms and invariants, authoritative data and schema owners, actors, object/action authority boundaries, data sensitivity, and failure modes. Record unanswered questions rather than inventing policy. Start templates/api-design-brief.md.
- Choose the interface shape. Compare interaction direction, coupling, delivery needs, query flexibility, mutation semantics, caching, observability, and evolution surface. Read references/interface-selection.md. Record the choice and rejected options in the brief; use an ADR only when the choice is consequential beyond this interface.
- Make the contract explicit. Define representations and their semantics, including null versus absent, defaults, enums/unions, identifiers, timestamps, units, ordering, filtering, and pagination. Use templates/endpoint-contract.md with references/contract-semantics.md.
- Design mutation and failure behavior. Define authority checks, preconditions, idempotency scope and equivalence, retries, concurrency, partial outcomes, long-running operation state, errors, and resource limits. Read references/operations-and-failures.md and create templates/error-taxonomy.md when errors are shared across operations.
- Describe asynchronous delivery where relevant. For messages, webhooks, or streams, state the publisher/subscriber perspective, envelope, delivery contract, duplicate/gap/reordering behavior, ordering scope, and security boundary. Read references/events-webhooks-streaming.md.
- Assess change from each consumer's perspective. Inventory consumers, generated clients, strict decoders, signatures, caches, quotas, and operational dependencies. Complete templates/compatibility-change-assessment.md. Do not call a change safe solely because it is additive.
- Plan and verify rollout. For a deprecation or migration, use templates/deprecation-migration-plan.md and references/evolution-and-deprecation.md. Review the contract using templates/contract-review.md. Test provider conformance, consumer expectations, compatibility diffs, examples, negative cases, and the deployed boundary.
Reference Guide
| Load when | File |
|---|---|
| Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streaming | references/interface-selection.md |
| Modeling data, collection reads, schemas, or OpenAPI | references/contract-semantics.md |
| Designing writes, errors, retry behavior, limits, or authorization handoff | references/operations-and-failures.md |
| Designing event contracts, webhook delivery, or streams | references/events-webhooks-streaming.md |
| Reviewing compatibility, versions, deprecation, migration, or rollback | references/evolution-and-deprecation.md |
| Preparing contract/provider/consumer/deployment verification | references/contract-verification.md |
| Checking exact sources, versions, status, and intended use | references/source-index.md |
| Exercising required edge cases before claiming readiness | references/scenario-probes.md |
Security Boundary
Document authentication requirements and server-side object/action authorization in the interface contract. For the threat model, credential handling, tenant isolation, untrusted URLs or files, webhook signature design, output minimization, redaction, or abuse resistance, load secure-software-engineering. An API contract cannot prove that an authorization boundary is enforced.
Completion
Stop when the selected interface has an owner, an authoritative contract, explicit consumer and failure assumptions, a compatibility assessment for each change, and evidence or an explicit gap for each required review item. Escalate unresolved domain semantics, authority, delivery, or consumer-impact questions to their accountable owner.