Your OpenAPI file marks shipping_address as required on GET /orders/{id}. After Tuesday’s deploy, about one response in 300 leaves it out, because a new code path for orders created by the import job skips the field. The docs still say required. The tests still pass, since nobody wrote one for import-job orders. A client with a strict deserializer starts throwing on 0.3% of order pages, and the first report you get is “sometimes the order screen is blank”.

You don’t get to decide which parts of your API are the API. Your users decide that, and they decide it by accident.

We removed a field once. It was called legacy_status, it duplicated a value that already existed under a better name, and it had been marked deprecated in the docs for a year and a half. Nobody read it. We checked the logs, checked the support tickets, checked with the two biggest accounts, and shipped the removal on a Tuesday.

A breaking change is any modification to an API that requires consumers to update their integration to continue functioning. The definition is straightforward. The practice of avoiding breaking changes while evolving an API requires engineering discipline that most teams underestimate until they have shipped a breaking change to a production API and experienced the resulting incident response.

The instinct to avoid defining something as a breaking change is strong. Removing a field that is not documented is tempting to classify as cleanup rather than a breaking change. Changing an error code from 400 to 422 for a validation failure seems like a trivial semantic correction. Adding a required field to a request body seems like a new feature rather than a breaking change. Each of these reclassifications is wrong, and each produces consumers whose integrations fail after the change.

API versioning is the discipline that separates API providers who have operated public APIs for several years from those who have not. Early-stage API design focuses on what the API should do. Mature API design focuses on how the API will evolve without breaking the consumers who have built on top of it. The difference in focus reflects a difference in experience with the consequences of getting it wrong.

Breaking changes are changes that require consumers to modify their integration to continue functioning. They include removing endpoints, removing fields from responses, changing field names, changing data types, changing authentication requirements, and changing the semantics of existing parameters. Every team that has shipped a breaking change to a public API without a migration path has received the same feedback from affected consumers, expressed with varying degrees of professionalism.