Versioning contracts — which changes require version bump, and which do not?

Versioning of contracts (APIs, interfaces) helps manage compatibility between clients and services. Changes are divided into:

• Compatible changes (do not require bumping the major version):

  • Adding new optional fields
  • Adding new methods that do not break existing functionality
  • Improvements that do not affect existing contracts

• Incompatible changes (require bumping the major version):

  • Deletion or renaming of fields/methods
  • Changing the data type in the contract
  • Changing the semantics of existing methods

Thus, if a change can break existing clients, the major version must be increased. Minor and patch versions are used for backward-compatible changes and fixes.