How do you test API versioning and backward compatibility?
60-second answer
I make sure existing clients keep working when the API changes. Additive changes, like a new optional field, should be safe, and I verify that old clients ignore unknown fields. Breaking changes, like removing or renaming fields, changing types, making a field required, or changing status codes, must go into a new version or follow a deprecation period. I test both versions side by side, run old consumer contract tests against the new provider, diff the OpenAPI specs automatically in CI to flag breaking changes, and check deprecation headers and documentation.
Explanation
Versioning styles: URL (/v2/orders), header (Accept: application/vnd.acme.v2+json), query (?version=2).
Tools:
oasdiff/openapi-diffto detect breaking changes between specs.- Pact for consumer expectations.
- Schema registry compatibility rules for events (Avro/Protobuf).
Mobile apps make this critical: old app versions stay in the field for months.
Example
A PR changed price from a number to an object {amount, currency}. The spec diff job in CI failed with "breaking: response property type changed", so the team introduced it as priceV2 instead.
Sample code
# Compare the PR's spec against main
git show origin/main:api/openapi.yaml > /tmp/base.yaml
docker run --rm -v "$PWD:/specs" -v /tmp:/base tufin/oasdiff \
breaking /base/base.yaml /specs/api/openapi.yaml --fail-on ERR