Versioned endpoints or oneOf union: which approach offers safer rollback for OpenAPI type changes?

Answer to the Core Question

When you need to change a field’s data type (e.g., string → integer) and guarantee a safe rollback, the versioned endpoint strategy is the safer choice. It isolates the new schema in a distinct URL (e.g., /v2/resource) while keeping the original endpoint (/v1/resource) unchanged, so clients that still rely on the old type never see a breaking change. oneOf unions can work, but they require the server and all tooling to accept both representations simultaneously, and rolling back demands that every variant remains valid, which increases the risk of validation errors.

Why Versioned Endpoints Win for Rollback

• Isolation of change – The old schema is preserved verbatim; no shared validation logic is affected.
• Clear deprecation path – You can retire /v1/resource at a later date without touching the new implementation.
• Gateway simplicity – API gateways route by path; no need for complex content‑type negotiation or schema‑based routing.
• Documentation consistency – Each version can have its own Swagger UI page, preventing confusion about which schema applies.
• Test‑suite clarity – Separate tests per version avoid cross‑contamination; CI can run them in parallel.

Potential Drawbacks of oneOf Unions

• Both variants must be valid at all times, so a rollback can inadvertently invalidate clients that were already on the new type.
• Server-side validation logic becomes more complex, especially if the union grows to include multiple legacy types.
• API gateways that support content‑type based routing may need additional configuration; others may treat the union as a single schema and fail clients that send the old type.
• Documentation must show both possibilities, which can clutter the UI and mislead developers into believing the old type is still in use.
• Test suites must cover every variant and the rollback path, increasing maintenance overhead.

Practical Steps for a Safe Rollback with Versioned Endpoints

1. Define the new schema in /v2/resource and keep /v1/resource unchanged.
2. Mark /v1/resource as deprecated in the OpenAPI document and in the API gateway.
3. Deploy the new version behind an API gateway that routes /v2/… to the new service and /v1/… to the legacy service.
4. Run integration tests against both versions to confirm that clients using the old type continue to succeed.
5. When ready to roll back, replace /v2/resource with the original /v1/resource implementation and remove the deprecated flag.

Practical Steps for a oneOf Union (if you choose to stay on the same path)

1. Define the schema as oneOf with both string and integer variants.
2. Implement server‑side validation that accepts either variant.
3. Update the API gateway to allow content‑type negotiation if necessary.
4. Add unit tests that send both types and verify the response.
5. For a rollback, simply remove the integer variant from the union, but ensure that no client has switched to it yet.

What Diagnostic Detail Would Change the Recommendation?

If your organization has a strict constraint that all clients must use the same URL (e.g., due to hard‑coded endpoints in legacy systems), a oneOf union might become the only viable path. In that case, you would need to confirm:

• Do all clients already support the new type, or is the old type still in active use?
• Can your API gateway perform content‑type based routing reliably?

Without that information, the safest default remains versioned endpoints.