Backward compatibility, explained
Typical backward-compatible changes are additive: a new endpoint, a new optional parameter, a new response field that clients can ignore. Removing, renaming, retyping or re-meaning anything usually is not.
Backward compatibility is ultimately a property of behavior, not just of schemas. A change can pass every schema check and still break clients if defaults, units or ordering change. That is why traffic replay testing is used to confirm it.
Related terms
- Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.
- Semantic versioning (SemVer): Semantic versioning is a MAJOR.MINOR.PATCH numbering scheme where a major bump signals a breaking change, a minor bump adds backward-compatible features, and a patch fixes bugs.
- Contract testing: Contract testing verifies that an API provider and its consumers agree on the requests and responses they exchange, so either side can change without silently breaking the other.