Define behavior, not only shape
Status codes, retry guidance, idempotency, field semantics, and error payloads belong in the contract before implementation.
Open error patterns
Contract path
API Contracts Hub
A practical path for writing API specs that protect compatibility, retries, errors, versioning, webhook behavior, and release safety.
Start Here
Review schema diffs
Classify each change as safe, risky, or breaking and attach consumer action before release.
Review schema diffsPlan deprecation early
Usage reporting, migration windows, Sunset headers, and customer communication should be part of the contract.
Open deprecation guideDecision Matrix
| Stage | Example | Review value |
|---|---|---|
| Field addition | Usually safe, risky if clients reject unknown fields | Add contract note and consumer test |
| Enum expansion | Often breaking for generated clients | Require compatibility review and release note |
| Error shape change | Breaking when clients parse stable codes | Version error taxonomy and keep old fields |
| Webhook retry change | Can duplicate side effects | Require idempotency key and replay test |
Copy-Ready Block
# API contract review block Endpoint: - Method / path: - Consumer groups: Compatibility review: - Additive changes: - Risky changes: - Breaking changes: Runtime behavior: - Retry policy: - Idempotency key: - Error taxonomy: Release gate: - Consumer test: - Migration note: - Rollback plan:
How to Use This Hub Before an API Release
Use this hub whenever an API change could alter a consumer assumption. Shape changes are only one part of that risk. Consumers also rely on timing, retry behavior, enum meaning, pagination order, error codes, authentication rules, and undocumented side effects. A contract review should make those assumptions visible before the schema ships.
Start with the diff, but do not stop there. Classify every changed field, status code, event, and retry rule as safe, risky, or breaking. Then write the consumer action required for each risky item. If the action is “none,” explain why the old client still behaves correctly. If you cannot explain that, the change is not ready for release.
The strongest API specs connect release notes to runtime monitoring. A deprecation note is incomplete without usage reporting. A webhook change is incomplete without replay and idempotency tests. A versioning decision is incomplete without a migration window. The contract is not finished until the consumer path is as clear as the provider path.
Review Rubric
| Check | Pass condition |
|---|---|
| Compatibility | Each change is classified as safe, risky, or breaking. |
| Consumer action | External and internal consumers know whether code must change. |
| Runtime semantics | Retries, idempotency, pagination, and error payloads are explicit. |
| Release communication | Migration notes and deprecation windows are ready before launch. |
| Observability | Logs and metrics can identify mismatched clients after release. |
Failure Modes to Watch
- A schema diff passes but semantic behavior changed silently.
- Enum expansion is treated as safe even though generated clients may reject unknown values.
- Error payloads change without preserving stable codes.
- Consumers receive a migration note after the rollout has already started.
Owner Handoff
The handoff artifact should include the contract diff, consumer list, migration note, test evidence, and rollback decision. Keep it near the API spec, not only in a release ticket, so future contract work can reuse the same reasoning.
Example Contract Review
A small enum change is a good contract-review test. The provider may believe adding status=archived is safe because old clients can ignore it. Generated clients, switch statements, analytics jobs, and webhook consumers may disagree. The spec should name every known consumer, how unknown enum values are handled, and whether the old SDK needs a patch before rollout.
The release owner should attach a query for current traffic by client version, a schema diff, and a rollback choice. If rollback means hiding the new enum behind a feature flag, write that. If rollback means reverting the contract and replaying events, write that instead. The important part is that rollback is not guessed after consumers start failing.
Real Scenario Breakdown: Enum Expansion
An enum addition looks small in OpenAPI, but generated clients often compile exhaustive switches. Treat it as a consumer behavior review, not just a schema edit.
| Review item | Question | Evidence |
|---|---|---|
| Consumer inventory | Which clients parse refund_status? | Web, mobile, partner webhook, analytics job |
| Generated client risk | Does any SDK treat enum as closed? | Compile old SDK against fixture containing pending_review |
| Fallback behavior | What should unknown values display? | Unknown status maps to review_required UI state |
| Migration note | Who must act before release? | Mobile team updates switch before public rollout |
Quick Audit Checklist
Before treating this hub as complete for a real team, run a short audit. First, confirm the reader can leave the page with one artifact copied into their workflow. Second, confirm every linked article answers a different question instead of repeating the same definition. Third, confirm the page names a failure mode that would matter in production, not only during planning.
The most useful hubs behave like workbenches. A reader should be able to open the page, choose the relevant path, copy the block, and know what evidence to attach before review. If a hub only explains the topic, it becomes another article. If it helps the reader decide what to do next, it becomes a resource.
Core and Advanced API Articles
Contract Testing Plan: From OpenAPI to CI
Turn schema and behavior expectations into CI gates before a contract change reaches production.
Read articleWriting Backward-Compatible API Change Specs
Classify safe, risky, and breaking API changes before consumers discover them the hard way.
Read articleAPI Change Management for AI-Generated Clients
Manage API changes when clients may be generated from stale docs, old examples, or assistant output.
Read articleAPI Error Taxonomy for AI-Assisted Integrations
Design stable error codes, retry categories, and machine-readable failure details.
Read articleDesigning API Specs for Agentic Clients
Write API specs that prevent agentic clients from fabricating IDs, skipping dry-runs, or retrying destructively.
Read articleContract-First SDK Generation with Human Review
Split generated client code from hand-authored SDK ergonomics and review both against the contract.
Read articleEvent-Driven Systems: Specification Patterns
Define event schema versions, replay safety, orchestration choices, and consumer ownership.
Read articleMobile Push Notification Preference Spec
Treat notification preferences as a contract across device state, permissions, quiet hours, and consent.
Read articleWebhook Consumer Spec
Specify signatures, replay protection, retry order, and idempotent handling for webhook consumers.
Read articleVersioning Strategies for API Contracts
Choose versioning rules that match consumer risk, SDK timelines, and deprecation windows.
Read articleFAQ
What makes an API spec different from OpenAPI?
OpenAPI describes shape. A spec also names behavior: compatibility, retry semantics, failure handling, rollout expectations, and consumer communication.
When is a small change worth a contract review?
When it affects fields, errors, idempotency, authentication, rate limits, versioning, or any behavior that consumers might rely on.
Which fields belong in an API contract spec?
Include request and response schemas, error codes, idempotency rules, auth behavior, pagination, rate limits, webhook semantics, versioning, and deprecation policy.
How should breaking changes be handled?
Name the affected consumers, migration window, parallel version, telemetry that proves adoption, and the date the old behavior can be removed.
Should generated SDKs be part of contract review?
Yes. Generated SDKs still need review for naming, error ergonomics, retry defaults, examples, and compatibility with the published API contract.
When you need to use this today, open a template first, then come back to this hub for review and evidence checks.