api-design-and-evolution

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.

When not to use

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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. Load release-engineering for release sequencing, artifact promotion, progressive exposure, and coordinated rollback after the compatibility policy is defined.

Reference Guide

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.