API Versioning Strategies That Don't Break Your Customers' Integrations

An internal API can change whenever the team that owns it wants. A public API, the moment a single customer builds an integration against it, has effectively frozen — every field, every status code, every quirk of behaviour is now something someone else's production system depends on, whether or not you documented it as a guarantee.

Pick a versioning scheme before you need one

• URL versioning (`/v1/`, `/v2/`) — the most explicit and the easiest for customers to understand and pin against; the heaviest to maintain multiple copies of.
• Header-based versioning — cleaner URLs, easier to default sensibly, but customers forget to set the header and get surprised by changes.
• Date-based versioning (a la Stripe) — customers pin to the API version active when they integrated; you can ship breaking changes behind a version flag without forcing anyone to move.

We lean toward date-based versioning for anything with a meaningful external developer audience — it lets you evolve the API continuously without ever forcing an integration to break on a schedule you control but they do not.

The change that is never "just additive"

Adding a new required field, changing an enum's allowed values, or even reordering fields in a response some client happens to parse positionally — teams call these "minor" and ship them without a version bump, then field a support ticket from the one customer whose integration silently broke. Define, in writing, exactly what counts as a breaking change for your API before the first external integration exists, so the definition is not renegotiated under pressure later.

Deprecate on a calendar, not a whim

A published deprecation policy — minimum notice period, a sunset date communicated directly to affected API keys, not just a changelog entry — turns API evolution from a trust-eroding surprise into a predictable, professional process. The teams that get this right treat their API version history the way they treat their uptime SLA: a commitment, not a suggestion.