Path Versioning or Header Negotiation for OpenAPI Schema Rollback

Question

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?

Tasadduq Burney · Answer

Answer
Path‑based versioning (e.g., /v1 and /v2) is the approach that best preserves existing client compatibility when you need to roll back a breaking OpenAPI schema change without regenerating clients.
Why this is the case (confirmed facts)

OpenAPI 3.0/3.1 documents are static; they cannot contain a dynamic “rollback link” or advertise that an earlier schema version is still available unless you expose it through a version‑specific path or header.
The deprecated keyword only marks an operation for removal; it does not provide a replacement version or automatic client‑side switch.
Path versioning isolates each schema in its own codebase/OpenAPI file, so traffic sent to /v1 continues to receive the legacy schema regardless of what is deployed under /v2. This enables an immediate rollback by shifting traffic back to the /v1 endpoint at the API gateway or load balancer.
Header‑based negotiation (e.g., Accept: application/vnd.api.v1+json) keeps a single URI but requires the client to send the appropriate header. If a client cannot change its header dynamically, an unplanned rollback cannot be honored without client updates.

Steps to implement a rollback‑ready path‑versioned API

Maintain two separate OpenAPI definitions: openapi-v1.yaml for the legacy schema and openapi-v2.yaml for the breaking version.
Deploy each definition to its own backend service (or to the same service with distinct routing rules) versioned as /v1 and /v2.
Configure your API gateway / load balancer to route:

/v1/** → v1 backend
/v2/** → v2 backend

When a breaking change is deployed to /v2, monitor for issues.
If a rollback is needed, update the gateway rule to send /v2/** traffic to the v1 backend (or simply disable the v2 backend and let the gateway fallback to v1). No client code change is required.
Optionally keep the deprecated flag on v2 operations to signal future removal.

Missing diagnostic detail
To confirm that this recommendation fits your environment, please verify whether your API gateway or ingress controller supports path‑based routing and can switch traffic between backends without downtime or config reload.

Path Versioning or Header Negotiation for OpenAPI Schema Rollback

Goal

Constraints

Questions

1 answer

Answer

Why this is the case (confirmed facts)

Steps to implement a rollback‑ready path‑versioned API

Missing diagnostic detail

Your perspective belongs here.

0 question comments