Changes

Change is the great enemy of a successful API. An API is a contract, and the entire value of a contract is that the other party can depend on it. The moment you change the contract, you risk breaking everyone who relied on the old one. Versioning is the mechanism the industry invented to manage that tension — a way to evolve an API without instantly betraying everyone consuming it. But after fifteen years of watching how versioning actually plays out, I’ve come to believe that the technical mechanics of versioning are the easy part, and the hard part — the part almost everyone underinvests in — is governing change as a discipline of communication, business alignment, and trust over time.

The most basic and most argued-about question is how you version: in the path, in a header, or through content negotiation by media type. The API purists have long insisted that path versioning — /v1/, /v2/ — is the wrong way, that versions belong in headers or in media types so the URL of a resource stays stable. And technically they have a point. But I’ve watched path versioning remain the utterly dominant pattern year after year, and in 2024 I found that five of the seven top API providers I looked at — Adidas, Microsoft, Azure, Google, Cisco, Atlassian among them — version in the path or URI. People put the version in the URL because it’s easier for them and easier for their developers to understand. That’s the whole reason. And it pushed me to a deliberately provocative reframe: if nearly everyone does versioning “wrong,” maybe wrong is right. Maybe the pattern that’s legible to the most humans, that you can see and reason about just by reading the URL, is actually the correct one regardless of what the architectural ideal says. Governance has to start from how people actually behave, not from how the spec says they should.

Underneath the where-to-put-the-version question is the more important one: what actually counts as a breaking change. Google’s versioning guidance gave the canonical technical taxonomy — backwards-compatible changes you can make freely, like adding optional fields or new endpoints, versus backwards-incompatible ones that require a new major version, like removing fields, changing types, or changing HTTP bindings. Adidas codified the same instinct as rules: you must not take anything away, must not change processing rules, must not make optional things required, and anything you add must be optional. That’s the robustness principle applied to API evolution, and it’s the heart of additive, non-breaking change — you can grow an API almost indefinitely without a new version as long as you only ever add, and only ever add optionally. Semantic versioning, MAJOR.MINOR.PATCH, gives you the vocabulary to signal which kind of change you’ve made. A huge amount of versioning pain disappears the moment a team internalizes that most changes don’t need to be breaking if you design for extension from the start.

But I’ve increasingly argued that the technical definition of a breaking change is too narrow, and this is where change management becomes a genuine governance and business question rather than an engineering one. Is a price change a breaking change? Is a change to your rate limits, your terms of service, your privacy policy, your authentication requirements? For the consumer whose business depends on your API, a pricing change can be far more breaking than a renamed field — it can end their use of your platform entirely. Yet we track technical breaking changes with diffing tools and CI pipelines while business breaking changes get almost no rigor at all. If we’re serious about governing change, the breaking-change taxonomy has to expand to include the business surface of the API, not just its technical schema. The contract a consumer depends on is never only the OpenAPI; it’s the price, the limits, the terms, and the stability of all of them together.

Tooling has caught up on the technical side, at least, and detecting breaking changes is now something you can automate and govern. You take two versions of an API definition, diff them, and determine programmatically whether the change is breaking — passing or failing it in the CI/CD pipeline before it ever ships. I’ve explored how genuinely complex an OpenAPI diff is, though — host, base URL, paths, verbs, parameters, schemas, references, each a layer with its own nuance — so this is harder than it sounds. But the direction is right: breaking-change detection belongs in the pipeline as an automated governance gate, alongside Spectral rules and design linting, so that a breaking change becomes a deliberate, reviewed decision rather than an accident someone discovers in production. Versioning governance is increasingly a set of policies and rules — for OpenAPI versioning, semantic versioning, and path versioning — enforced automatically rather than left to each team’s discretion.

The piece of change management that gets the least attention and matters the most is communication. I’ve observed for years that there are endless conversations about how to version an API and almost none about how to communicate each version. This is where the changelog comes in, and the changelog is an essential building block, distinct from the versioning scheme itself. Versioning is how you structure change; the changelog is how you tell people about it. Paired with a roadmap, the changelog turns change from something that happens to consumers into something they can see coming, plan for, and trust. Documentation is the face of change — the best change-management platforms understand that. When the Department of Labor published a mundane, clear API deprecation notice, I celebrated it precisely because boring, predictable, well-communicated change is the goal. GitHub announcing an individual property change — a retention period adjustment — is the kind of granular communication that respects consumers. The discipline isn’t avoiding change; it’s never surprising anyone with it.

Deprecation is the end of the change lifecycle, and it deserves the same governance rigor as everything upstream. I’ve laid out the common building blocks of deprecation: the types (an individual endpoint, a tool, a whole platform), the runway (from the decision, to the first notice, to lock-down, to the final date), the communication schedule, the migration tooling, and the support through the transition. Good deprecation is far more communication than legal — Google has long been the gold standard, with predictable notice periods that treat their prior commitments as obligations. The worst deprecation is the API that just quietly fades into a 301 redirect with no notice. Sunsetting an API well is a planned, communicated, multi-stage process, not an event that happens to people.

I pulled the whole thing together under the idea of provenance — that managing change requires a balanced business and engineering approach, aligned with consumers, that carries the provenance of every change from day one. The dozen policy areas I mapped span repository, contracts, design, use cases, versioning, roadmap, changelog, SDKs, support, feedback, communication, and policies. Versioning is just one item on that list. Change management is the whole list working together, with a traceable history of what changed, why, and who it affected. Co-producing the Breaking Changes podcast at Postman — over 130 episodes — reinforced this for me: the governance conversations were rarely about design rules and almost always about people, about productization, about enterprises struggling with stability and legacy at scale. Change is a human and organizational problem wearing a technical costume.

Which brings me to my most provocative position, the one I landed on in 2025: API versioning is largely an engineering coping mechanism amidst unrealistic business deadlines. Versioning, at the enterprise scale where I’ve watched it, is often theater — a response to the perpetual unrealistic deadlines imposed on engineers, to their lack of control, and to their inability to resist the velocity the business demands. Teams cut a new version not because the API genuinely needed to break, but because breaking was easier than doing the harder, slower work of designing for extension and holding the line on stability under deadline pressure. I don’t say this to dismiss versioning — you need it, and done well it’s essential. I say it because the honest governance insight is that most breaking changes are a symptom of organizational dysfunction, not technical necessity. If the business gave engineering the time and the mandate to design stable, extensible contracts and to govern change deliberately, a great deal of versioning churn would simply never happen. Managing change over time isn’t fundamentally about choosing v1 versus v2 or path versus header. It’s about whether the organization is willing to treat its API as a durable contract worth protecting — and that’s a governance and business-culture decision long before it’s an engineering one.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Changes

References

Guidance Details

Explore more

Discover APIs