Our takes

The case for boring, stable API versioning

A provider announcing a major new API version is usually announcing, to every customer with an existing integration, a project they did not ask for. Even a well-communicated breaking change means someone has to schedule time to read a migration guide, update request or response handling, test it, and deploy it, on a timeline set by the provider's roadmap rather than by anything happening in that customer's own product.

We think API stability is worth treating as a design goal in its own right, not a lack of momentum. A response shape, once published, should keep meaning what it meant when a developer first built against it. New fields can be added as optional additions, the way elevation, IP threat, and network detail are opt-in extras layered onto standard responses rather than forced restructurings of them. What should not happen quietly is an existing field changing meaning, a status code being repurposed, or a shape being restructured under the same version number.

Part of why breaking changes happen so often across this industry is that they are cheap for the provider and expensive for the customer, and the two sides rarely negotiate over that imbalance directly. Shipping a cleaner internal model is a legitimate engineering win for a provider's own team. It becomes a burden the moment it forces every downstream integration to change in response, on a schedule the provider controls and the customer does not.

This does not mean an API should never change. It means changes should be additive wherever possible, and where a genuine breaking change is unavoidable, it should be rare enough that a customer can trust the shape they built against will still work months or years later, not something they need to monitor a changelog to defend against. Stability is not the same as stagnation. It is a promise that today's integration work does not have an expiration date attached to it that nobody told you about.

There is a selfish reason for us to hold this position too, beyond customer goodwill. Every compatibility host we run depends on matching another provider's shape faithfully over time, which only works if shapes, once matched, are worth relying on as stable targets. A company that treats its own API surface as disposable, to be redesigned whenever convenient, is a company whose compatibility guarantees are not really guarantees either. Stability has to be a habit that applies everywhere or it does not really apply anywhere.

Boring is not a criticism here. A version of an API that still works exactly the way it did when you first integrated it, years later, is not evidence that nothing improved. It is evidence that improvements happened in ways that did not require you to notice them, which is the entire point of good versioning discipline.