OpenAPI versioning that avoids breaking changes

Set clear version strategy

Decide whether clients select a version in the path, a header, or a media type. Document the choice and keep it consistent. APISAST looks for versioning signals in the contract; it does not compare deployed versions or decide which strategy is right for your users.

Use semantic versioning

Semantic versioning (MAJOR.MINOR.PATCH) helps clients understand impact. Breaking changes belong in MAJOR bumps; additive fields belong in MINOR; PATCH should be backward compatible. Document this in info.version and changelog sections of your OpenAPI file.

The static API security scanner can flag a non-semantic info.version and a deprecated operation without sunset information. Use a separate contract-diff check to detect breaking changes between versions.

Communicate deprecations

• Add the Deprecation header and a sunset date.
• Mark deprecated operations and schemas in OpenAPI with a rationale.
• Provide migration guides and examples in docs and error messages.

APISAST can flag a deprecated operation without sunset information. Keep authorization tests for older routes because a deprecation marker does not change runtime access control.

Prevent breaking changes

• Avoid removing fields; mark them nullable or deprecated first.
• Keep error formats stable and additive; don’t swap codes abruptly.
• Use feature flags and shadow deployments to test new shapes.

Pair static checks with consumer-driven contract tests to ensure clients still parse responses. See API security SAST tools for adding these checks to CI.

Document change logs

Keep a changelog beside the API reference and link to it from the API description. Each entry should explain the affected operations, client impact, and migration steps. APISAST does not validate changelog entries; review them with consumers and contract-diff results.

Distinguish the document version from the API version

The OpenAPI info.version describes the API definition, but consumers also need to know which interface version a request reaches. A path such as /v2/orders can make selection obvious; a header can keep paths stable but requires clear examples in docs and SDKs. Choose one strategy based on how clients are deployed, how long versions coexist, and how gateways route requests. Publish a migration guide before adding a second version.

Keep the contract for each supported version accessible and test it against the corresponding deployment. A single document that silently describes only the newest route makes older integrations hard to maintain. Record who owns each version and when support ends. APISAST can review a specification for versioning signals, but it cannot discover forgotten live endpoints; compare the deployed route inventory with your published contracts.

Test compatibility before changing a response

A new required request field, removed response field, changed enum, or different authentication requirement can break clients. Run a contract diff between the old and new OpenAPI files and review each flagged change with an API owner. Then run consumer tests with real SDK versions and representative payloads. An additive field is often safe, but clients that reject unknown fields may still fail; observe actual client behaviour instead of assuming every change is harmless.

Deploy a compatible transition when possible. Introduce the new field alongside the old one, document both, and give consumers time to migrate. Keep error codes and pagination semantics stable during the transition. If a breaking change is unavoidable, publish a new version and a concrete upgrade example. Static design checks and compatibility tests answer different questions, so keep both in the release process.

Retire an operation with evidence

Mark an operation deprecated in the contract and publish a replacement, a sunset date, and a contact path. Tell consumers which behaviour changes and how to test their migration. Measure calls to the old route by client identity where privacy policy allows. Do not remove a route simply because a dashboard shows little traffic; batch jobs may run only monthly, and some integrations have long release cycles.

Keep legacy routes authenticated and monitored until removal. After the announced sunset, return a predictable response and retain enough logs to investigate unexpected callers. The shadow and zombie API guide covers inventory and cleanup after a migration. Check the live gateway configuration as well as the OpenAPI file so the old version is actually retired.

Next steps

Run APISAST to check for versioning gaps, then visit the OpenAPI security scanner for more static analysis tips or the SAST testing for APIs guide to add automation.