URI Versioning or Header Versioning for Safe Rollback After Breaking Schema Changes

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?

• Which versioning style provides clearer isolation for rolling back a breaking change while still allowing automated detection via OpenAPI?
• How does each style work with the deprecated property to signal removal without immediate failure?
• What are the practical trade‑offs concerning caching, client‑side debugging, and maintenance overhead when attempting a rollback?