Breaking change policy documented
Why it matters
Without a documented breaking change policy, consumers have no way to know which parts of the API are stable and which might change without notice. This matters most at integration time: a consumer building a production integration on an undocumented API is making a bet that the author's implicit stability expectations match their own. When they don't, the consumer's code breaks silently on the next deploy. iso-25010:2011 compatibility.interoperability requires that the API's stability guarantees be explicitly stated — not assumed from silence.
Severity rationale
High because undocumented breaking change policies mean consumers cannot make informed integration decisions and have no recourse when changes break their code.
Remediation
Add an API stability section to your README or API documentation that explicitly defines what is and is not a breaking change:
## API Stability
This API follows semantic versioning. Within a major version:
- Existing fields will not be removed or renamed
- Existing endpoint paths will not change
- Response types will not change
- New optional fields may be added to responses
- New optional parameters may be added to requests
Breaking changes (field removal, type changes, endpoint removal)
will only occur in major version bumps with a minimum 90-day
deprecation notice.
The policy must cover at least: field removal, type changes, endpoint removal, required field additions, and status code changes.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the API Design Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · compatibility.interoperability — Interoperability — documented breaking-change policy defines the consumer contract
- iso-25010:2011 · maintainability.modifiability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from api-design·automated