Versioning, Evolution and Breaking Changes

Change without breaking clients

APIs change; the goal is to change them without breaking existing clients. Backward-compatible changes include adding new endpoints, adding optional request fields or parameters, and adding response fields (provided clients ignore unknown fields). Breaking changes include removing or renaming endpoints, fields or parameters, making an optional input required, changing types or formats, narrowing enums in requests, adding enum values that strict clients cannot handle, changing status codes, and changing authentication requirements. Strategies: keep changes additive; mark old elements deprecated: true with a description of the replacement and a sunset date (the Sunset and Deprecation HTTP headers can signal this at run time); introduce a new major version (/v2 path, header or media type) only for unavoidable breaks; and run old and new versions side by side during migration. Automate detection: tools such as oasdiff and other OpenAPI diff tools compare the previous and new documents in CI and fail the build on breaking changes. Use semantic versioning in info.version to communicate impact.

Detecting breaking changes in CI

Compare the main branch's document with the pull request's version.

# fetch the published contract from main and compare it with the PR version
git show origin/main:api/openapi.yaml > /tmp/openapi-main.yaml

oasdiff breaking /tmp/openapi-main.yaml api/openapi.yaml --fail-on ERR
# examples of what it flags:
#   removed path GET /orders/{orderId}/invoice
#   request property 'couponCode' became required
#   response property 'total' type changed from string to number

# additive changes (new optional field, new endpoint) pass
oasdiff changelog /tmp/openapi-main.yaml api/openapi.yaml

Adding rooms versus moving walls

Adding a new room to a building disturbs nobody. Moving a load-bearing wall or a staircase that people already use needs warning, a temporary route and a deadline. API changes work the same way.

त्वरित जाँच: Which change to a public API is usually breaking?

• Adding a new optional query parameter
• Adding a new endpoint
• Adding a new field to a response
• Making a previously optional request field required