Versioning without breaking your partners
Inside your own walls, a breaking API change is a refactoring: you find the consumers, update them, and ship everything together. The moment an API has external consumers, that option disappears. Every breaking change you publish becomes a project in someone else's roadmap, scheduled by their priorities, staffed by their engineers, delivered on their timeline, which is to say, possibly never.
This is the fundamental asymmetry of B2B APIs: you control the interface, but your partners control the pace. Versioning strategy is how you live with that asymmetry gracefully.
Rules that survive contact with partners
- Additive by default. New optional fields, new endpoints, new enum values your consumers were told to tolerate: most evolution never needs a version at all, provided the contract said so from day one.
- Version seldom, and mean it. A major version is a promise of long cohabitation. Two live versions is a burden; three is a museum you are paying to heat.
- Deprecation is a relationship, not a header. A sunset date in the documentation reaches the partners who read documentation. The ones who will call you in a panic are, by definition, the others.
A version's lifecycle ends not when you switch it off, but when the last consumer has somewhere better to be. Your job is to make that journey short and unsurprising.
Design the contract for change up front
Most breaking changes are not forced on you; they are the result of a contract that was too specific about things that were going to move. An API that returns a fixed, closed set of fields, rejects anything it did not expect, and bakes today's assumptions into required parameters is an API that will need a new version the first time reality shifts. One designed to tolerate the unknown, optional additions, clients told to ignore fields they do not recognize, enums that may grow, absorbs years of evolution without a single breaking release.
This is worth investing in early, because the cost asymmetry is brutal. A small amount of forethought in the original contract saves every consumer a migration project later. The teams that treat the first version of a public API as a durable, carefully designed interface, rather than as whatever their internal model happened to look like, spend far less of the following decade coordinating breaking changes across partners who never asked for them.
What the platform should do for you
Policy is only half of it; the other half is knowing the truth. The gateway sees exactly which consumers still call the old version, how often, and for what. That turns deprecation from broadcast into conversation: the account team contacts the seven partners who are actually affected, with usage figures in hand, months before the date. Routing can then migrate consumers individually, with the stragglers given compatibility shims rather than ultimatums.
On Waygrid, versions, consumers, and their traffic live in one place, so "can we retire v1 yet?" is a report rather than a debate. The technical mechanics of versioning, paths, headers, media types, matter far less than teams enjoy arguing about. What partners remember is whether change arrived with notice, numbers, and a path, or as a Tuesday-morning outage with your name on it.