A payments team restructures the `amount` field on `GET /orders/{id}` from a bare integer of cents to a structured object carrying `value` and `currency`, because bolting multi-currency support onto a plain integer had become unworkable. The new shape is a genuine improvement, reviewed and merged cleanly, and deployed straight to the existing endpoint the moment CI goes green. Within minutes, every integration that parsed `amount` as a number throws on the object it now receives, invoice emails stop rendering a total, and a partner's overnight reconciliation job quietly records zero for every transaction it processed that day. No consumer team wrote careless code — each one built against the exact contract the endpoint offered on the day they integrated. What broke was the assumption that the same URL would keep meaning the same thing indefinitely.
Versioning exists to make that assumption safe to hold. It draws an explicit line between the contract a consumer already depends on and any contract the provider wants to offer next, so the provider can genuinely improve an API without every existing integration having to change on the provider's deploy schedule. Without that line, a team is left choosing between two costly extremes: freeze the API's shape indefinitely because any change might be somebody's breaking change, or ship improvements and treat the resulting incidents as the price of progress. Versioning turns that binary into something workable — the old contract keeps behaving exactly as documented, a new one exists alongside it, and each consumer decides on its own schedule when it is ready to move, rather than being forced to move the instant the provider does.
Analogy🏏Cricket
🏏 Think of it like cricket: When South Africa needed 22 runs off the final ball to win the 1992 World Cup semi-final against England, the rain-revised target had been recalculated by a method so crude it treated a rain delay as if the required run rate simply carried forward untouched, producing a target no team could physically reach off one ball. The tournament had committed to that calculation method before a ball was bowled, and nobody rewrote the semi-final's result afterward — the target stood exactly as the rules in force that day produced it. What changed was every match played after it: cricket adopted the Duckworth-Lewis method, and years later the refined Duckworth-Lewis-Stern version, as the new calculation for rain-affected targets, published as its own named standard rather than silently patched into the old one. Just as the 1992 semi-final was decided entirely under the target-setting rule the tournament had already committed to, an API request already in flight is served entirely under the contract version it was made against — a later fix does not reach back and rewrite it. Just as Duckworth-Lewis and later DLS shipped as clearly named, separately adopted methods rather than a silent rewrite of how the old numbers were calculated, a breaking API change ships as a new, distinctly addressable version rather than a silent mutation of the one consumers already call. The insight is that a rule consumers already relied on has to keep producing the result it always produced, and a better rule belongs in a new version consumers can adopt on purpose, not in a patch applied underneath them.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.