Someone renames a field, tightens a validation rule, or restructures a response, and by the next morning three integration partners are filing tickets about a production outage they didn't cause. Nothing about the change looked risky from inside the codebase. From the outside, it was a breaking change shipped with no warning, no migration path, and no version to fall back to.
This is the exact failure mode API versioning exists to prevent, and it's worth understanding both why it happens and what a real versioning strategy actually looks like in practice, beyond just sticking a v1 in the URL and calling it done.
Why "It's Just a Small Change" Is a Dangerous Assumption
Every API has an implicit contract with whoever is calling it: these fields exist, they mean this, they're structured this way. Clients get built against that contract, often by teams with no visibility into your codebase and no reason to expect it will shift under them.
A change that looks small from the server side, renaming a field, changing a status code, tightening what counts as valid input, can silently break a client that parses the response a specific way or depends on the old validation being lenient. The server team rarely finds out until support tickets start arriving, because there's no build step, no compiler, and no automated warning that tells an external client its integration just stopped working.
Semantic Versioning Isn't Just for Package Managers
Semantic Versioning is best known from package managers, but the underlying idea, major versions for breaking changes, minor versions for backward-compatible additions, patch versions for fixes, applies directly to API design. Adopting that discipline for an API means being explicit, every time a change ships, about which category it falls into, rather than treating every deploy as equally safe.
The discipline matters more than the specific numbering scheme. A team that internally tracks "is this additive or breaking" before every API change catches accidental breaking changes before they ship, simply by forcing the question to be asked at all.
Photo by Brett Sayles on Pexels
Choosing How to Expose the Version
There are a few established ways to expose API versioning to clients, and each has real tradeoffs:
- URL path versioning (
/v1/orders,/v2/orders): the most visible and easiest for client developers to understand at a glance, at the cost of duplicating routes across versions internally. - Header-based versioning (a custom header or an
Acceptheader content-type parameter): keeps URLs stable across versions, which some teams prefer for caching and tooling reasons, but is easy for client developers to overlook if they're not reading documentation closely. - Query parameter versioning (
?version=2): simple to implement, but easy to omit accidentally, which silently defaults a client to whatever the current version happens to be.
None of these is universally correct. URL path versioning tends to be the most forgiving default for public APIs with a wide, less sophisticated client base, since the version is impossible to miss. Header-based versioning suits internal or partner APIs where client teams are already reading integration docs closely.
What Actually Counts as a Breaking Change
A shorter list than most teams expect, but worth being precise about:
- Removing a field, an endpoint, or a parameter.
- Renaming a field or endpoint.
- Changing a field's data type or its meaning, even if the type stays technically the same.
- Adding a new required field to a request.
- Tightening validation on an existing field in a way that rejects previously valid input.
- Changing the meaning of an existing status code.
Adding a new optional field to a response, adding a new optional request parameter, or adding a new endpoint are all backward-compatible by default and don't require a version bump, as long as existing clients that ignore unfamiliar fields keep working unaffected.
Deprecation Windows: The Part Most Teams Skip
Announcing a new version is the easy half. The harder, more frequently skipped half is giving a real deprecation window before retiring the old one. A deprecation window means the old version keeps working, unchanged, for a defined period, communicated clearly, while clients migrate on their own schedule rather than yours.
What counts as "enough time" varies by how many external integrators depend on the API and how actively they maintain their integrations. A public API with unknown third-party consumers generally needs months, not weeks. An internal API with a small number of known consuming teams can move faster, since coordination is a conversation rather than a broadcast into the unknown.
"The API changes that actually cause outages are almost never the ones teams debate carefully before shipping. They're the ones that felt too minor to bother versioning, and that's exactly why every breaking-versus-additive decision needs a deliberate check, not a gut call made in the middle of an unrelated feature." - Dennis Traina, founder of 137Foundry
Versioning Internal APIs Differently From Public Ones
Not every API needs the same level of ceremony. An API consumed only by a team's own front end, deployed and released together in lockstep, can often get away with looser versioning discipline, since the client and server ship as a unit and there's no external party depending on backward compatibility.
The moment an API has any consumer outside that lockstep deployment, another team, a partner, a mobile app that can't force every user to update immediately, the calculus changes completely. Mobile clients in particular deserve extra caution: a mobile app update can take days to propagate through app store review and user adoption, which means an API serving mobile clients needs a meaningfully longer deprecation window than one serving only a web front end that redeploys in minutes.
Testing for Breaking Changes Before They Ship
Manually reviewing every API change for breaking-versus-additive status works until it doesn't, usually right around the point a team is moving fast enough that careful review starts getting skipped under deadline pressure. Automated contract testing closes that gap: a test suite that validates every response against the documented OpenAPI contract for each supported version catches an accidental field removal or type change before it reaches production, regardless of whether anyone remembered to think about versioning that day.
This is also where having the contract documented formally, rather than living only in engineers' heads or scattered across old pull request descriptions, pays for itself. A machine-readable contract is something a test suite can actually check against. Institutional memory isn't.
Communicating Version Changes to Client Developers
A version bump that isn't documented and announced is nearly as disruptive as a silent breaking change, just slower to surface. Changelog entries, deprecation headers on API responses that flag an old version's retirement date, and direct outreach to known integration partners for anything high-impact all reduce the number of clients who find out about a change from a broken production request instead of from documentation.
Stripe is a widely cited example of doing this well: versioned API releases, a long-standing deprecation policy, and account-level version pinning that lets individual integrations stay on an older version even as the platform moves forward. The specifics don't need to be copied exactly, but the underlying principle, giving clients real control over when they migrate, is worth internalizing regardless of API size.
Photo by Jakub Zerdzicki on Pexels
Documenting the Contract So It's Actually Enforceable
A versioning strategy is only as good as the documentation backing it. Tools built around the OpenAPI specification let a team define the exact request and response contract for each version formally, which makes it possible to catch accidental breaking changes with automated contract tests rather than relying on a human noticing during code review. The IETF's HTTP semantics specification remains the underlying reference for how status codes and content negotiation are supposed to behave, which matters most for header-based versioning schemes.
Treating the documented contract as a real gate, not just reference material, is the difference between a versioning policy that's followed and one that quietly erodes the first time someone's under deadline pressure.
Photo by Oscar Chan on Pexels
A Practical Versioning Checklist
Before shipping any API change, work through this in order:
- Classify the change: additive, or breaking. If it's ambiguous, treat it as breaking.
- If breaking, decide the version bump and how it will be exposed (path, header, or parameter).
- Write or update the OpenAPI contract for the new version before implementation, not after.
- Set a deprecation date for the old version, and put it somewhere clients will actually see it, not just an internal wiki.
- Communicate the change through changelog entries and, for high-impact changes, direct outreach to known integration partners.
- Keep the old version fully functional, unchanged, through the entire deprecation window.
Getting This Right the First Time
A versioning strategy retrofitted onto an API that's already accumulated years of undocumented, ad-hoc breaking changes is a much bigger project than building one in from the start. For teams building or maintaining an API that other software depends on, 137Foundry's web development team works through exactly this kind of contract design, from initial versioning strategy to migrating a legacy API onto a defensible one without breaking the clients already depending on it.
For more on how the underlying architecture decisions behind a project affect how much technical debt accumulates over time, 137Foundry's services page covers the broader range of engineering work the team takes on, and the About page has more on how the team approaches this kind of work.
