API versioning strategy exists
Why it matters
An unversioned API has no mechanism to introduce breaking changes without breaking every existing consumer simultaneously. The first time a field is renamed, an endpoint is removed, or a response type changes, all integrators are affected with no warning or migration path. iso-25010:2011 compatibility.interoperability and maintainability.modifiability both require that the API surface area be stable across releases — and versioning is the mechanism that makes stability promises credible. Adding /v1/ retroactively after you have external consumers is far more disruptive than doing it before launch.
Severity rationale
Critical because an API with no versioning cannot introduce breaking changes without immediately breaking all consumers, making the API contract permanently fragile.
Remediation
Add URL-based versioning to all endpoints now, before external consumers lock in on your paths:
// Before:
/api/users
/api/orders
// After:
/api/v1/users
/api/v1/orders
For GraphQL, version via @deprecated directives and a documented deprecation timeline rather than URL versioning. For gRPC, add package versioning to your .proto files: package myapi.v1;. If you already have consumers on unversioned paths, add a redirect layer from /api/ to /api/v1/ while you migrate client code.
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 — versioning strategy enables backward-compatible evolution
- iso-25010:2011 · maintainability.modifiability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from api-design·automated