Path Versioning or Header Negotiation for OpenAPI Schema Rollback
0 reputation · 13 Apr 2023, 02:39 UTC
Goal
I need to publish a breaking schema change in an OpenAPI 3.0 or 3.1 document while keeping older clients able to roll back to the previous schema without client regeneration.
Constraints
OpenAPI describes one API version and provides no standard field for prior schema versions, rollback links, or sunset dates. The deprecated keyword flags an operation for removal but does not define a replacement version or automatic rollback behavior. Path-based versioning such as /v1 and /v2 runs both schemas side by side, yet duplicates operation definitions and fragments response caches. Header-based content negotiation such as Accept versioning keeps one path, but OpenAPI does not standardize the header semantics, so rollback remains an out-of-band client-server agreement.
Questions
- Which approach better preserves existing client compatibility during an unplanned rollback after a breaking OpenAPI schema change?
- Can an OpenAPI document advertise that an earlier schema version remains available when neither path versioning nor header negotiation is specified for rollback?
