Question
URI Versioning or Header Versioning for Safe Rollback After Breaking Schema Changes
Mira Vale
0 reputation · 19 May 2022, 20:10 UTC
74.4K views
Loading…
0 reputation · 19 May 2022, 20:10 UTC
When a breaking schema change must be rolled back, teams need a versioning approach that lets them revert to the previous contract without breaking existing clients while still enabling automated compatibility checks.
The OpenAPI Specification offers two common patterns: URI versioning (e.g., /v1/resource) and header versioning (e.g., Accept: application/vnd.myapi.v1+json). Both rely on the specification’s additive‑change rule and the optional deprecated property to signal phased removals, but the spec does not define a machine‑readable way to label a change as “breaking” for automated testing.
Given the need to balance isolation, rollback safety, and tooling support, which pattern better satisfies these constraints?
deprecated property to signal removal without immediate failure?30275 reputation · 20 May 2022, 06:21 UTC
For safe rollback after breaking schema changes, URI versioning (e.g., /v1/resource) is the superior choice. It provides the strongest isolation between incompatible contracts, allowing you to route traffic to entirely separate service clusters that are compatible with specific schema states.
URI versioning enables physical or logical isolation at the routing layer (API Gateway or Load Balancer). If a breaking change in v2 causes system instability, you can redirect traffic back to the v1 cluster immediately without redeploying code or altering client headers.
Regarding OpenAPI detection, neither style provides a native "breaking change" flag. However, URI versioning allows you to maintain distinct OpenAPI documents for each version. Automated tools can then perform a diff between the v1.json and v2.json specifications to detect breaking changes (such as removed fields or changed types) before deployment.
swagger
openapideprecated PropertyBoth styles utilize the deprecated: true property to signal a phased removal, but the execution differs:
v1 path as deprecated. Clients see a clear signal that the endpoint they are hitting is slated for removal, encouraging a migration to v2.| Constraint | URI Versioning | Header Versioning |
|---|---|---|
| Caching | Simple; unique URLs ensure unique cache keys. | Complex; requires Vary: Accept to prevent cache collisions. |
| Debugging | High visibility; version is explicit in the URL. | Lower visibility; requires inspecting request headers. |
| Maintenance | Higher risk of "version sprawl" in the codebase. | Higher internal routing complexity. |
It is assumed that the database schema is managed via the Expand and Contract pattern. No versioning strategy can recover a rollback if a column was physically dropped from the database. The schema must support both versions (additive changes) until the rollback window is closed.
To verify rollback safety, deploy two service instances (v1 and v2) pointing to the same database. Use a proxy to route traffic: verify that /v1/ requests ignore new schema additions and /v2/ requests utilize them. A successful rollback is confirmed when shifting all traffic to /v1/ restores stability without data loss.
Missing Detail: Are you utilizing a shared database across versions, or is each version backed by a separate data store/view?
Use comments to ask for clarification. Post a solution as an answer.
30,275 reputation · 20 May 2022, 03:19 UTC
When rolling back a breaking schema change, URI versioning lets an API gateway instantly redirect /v2/* traffic to the /v1/* cluster without touching client code, because the version is part of the request path and thus a distinct cache key. Header versioning, by contrast, requires changing the default media type (e.g., making application/vnd.myapi.v1+json the fallback) and relying on proxies to honor Vary: Accept; otherwise stale cached responses for the wrong version may be served. A practical hybrid approach is to use URI versioning for major, breaking releases and header versioning for backward‑compatible minor updates, which keeps routing simple while still allowing fine‑grained content negotiation.