Why synchronised breaking changes happen by default
It's structurally easier to maintain one version of an API than several in parallel, which creates a natural incentive to force everyone onto the new version quickly. That incentive is real for the maintaining team and genuinely costly for every consumer who didn't plan their own roadmap around your release schedule.
The honest trade-off is maintenance cost for the API provider versus migration cost for every consumer, and defaulting to minimising your own cost at their expense is a relationship decision disguised as a technical one.
What a consumer-respecting versioning strategy looks like
Additive, backward-compatible changes by default, genuinely breaking changes reserved for a new major version with a long, clearly communicated deprecation window for the old one, and a documented migration guide published alongside the new version rather than after consumers start complaining, respects the other side of the integration relationship.
Forcing every consumer onto your new API version on your timeline isn't an inevitable cost of evolving an API. It's a choice about whose roadmap matters more.MNB Integration Practice
Key actions
- Default to additive, backward-compatible changes
- Reserve breaking changes for a clearly versioned major release
- Publish a long, explicit deprecation window for old versions
- Release migration guides alongside the new version, not after complaints