Breaking change, explained
Breaking changes come in two forms. Contract breaks change the shape of the API, such as a removed field or a new required parameter. Behavioral breaks keep the shape but change meaning, such as amounts switching from dollars to cents.
Providers manage breaking changes with versioning, deprecation and migration guides; consumers absorb them through migrations. Detecting them reliably takes both spec comparison and behavioral verification.
Related terms
- Backward compatibility: An API change is backward compatible when every client built against the previous version keeps working, with the same behavior, after the change ships.
- API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.
- API versioning: API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.