API Versioning: Evolve Without Breaking Integrations

TL;DR — API versioning is the discipline of evolving a contract while customers still depend on the old one. Prefer additive changes inside a stable version. Create a new version only for a breaking change, then run both versions long enough for real customers to migrate with evidence.

An API can look private until the first script, partner, mobile app, or customer workflow depends on it. From that moment, changing a field name is not a refactor; it is an external product change. API versioning creates a clear promise about what changes are safe, what requires migration, and who owns the end date of old behavior.

The founder decision is to treat compatibility as a product cost before the integration base is large. Retrofitting a policy after customers have copied an endpoint into jobs is expensive and stressful.

Define breaking before you choose a URL

Adding an optional response field is usually compatible. Removing or renaming a field, changing a field’s type or meaning, tightening validation, changing pagination behavior, or altering an error contract can break a client. Write those rules down. They are more valuable than an argument about whether the version belongs in /v2, a request header, or a media type.

Path versions are visible and easy for a developer to discover: /v1/customers. Header versions keep URLs clean but can be harder to reproduce in a browser or share in a support ticket. Both work if documentation, SDKs, logs, and monitoring consistently expose the selected version. Stripe’s API versioning documentation shows why a versioned API needs an explicit upgrade path, not just a label.

Avoid a new major version for every feature. That creates parallel systems and forces customers to choose between missing improvements and a risky migration. Add new fields, endpoints, or optional parameters when they preserve old meaning. A feature flag can let you validate a new server behavior with a small audience, but it does not erase the compatibility promise once the behavior reaches general users.

Plan a deprecation like a launch

A version has a lifecycle: announce, measure use, provide a migration guide, contact remaining users, and retire only after a stated deadline. The exact duration should follow your contracts and customer dependency, so do not invent a universal number. The important part is that every old version has an owner and a date rather than becoming permanent infrastructure.

Hypothetically, a product replaces total_cents with a decimal amount. Sending both fields in v1 might be safe if their meanings are documented. In v2, amount can become canonical. The migration guide should show request and response differences, state rounding semantics, and explain error changes. Asking customers to “update to v2” without those details turns support into reverse engineering.

Instrument by API key, endpoint, and version. A dashboard showing version traffic tells you whether an announcement reached real callers. It also surfaces unknown dependencies such as a dormant monthly job. Load testing should cover both versions during the overlap, because old behavior can consume capacity until it is retired.

Failures that turn a version into a trap

• A team calls a change non-breaking because its own frontend does not use the field.
• Documentation has a new version before the service, or SDK defaults disagree with both.
• A retirement date is public but no one measures remaining traffic.
• Different versions share data writes without defining how old and new representations reconcile.
• Error messages do not identify the version, so support cannot reproduce a report.

The difficult case is a security or correctness bug in an old contract. Fix the unsafe behavior promptly, state the impact precisely, and give customers a concrete path forward. A version label is not permission to preserve known harmful behavior forever.

Acceptance checklist

• Compatibility rules list what is additive and what is breaking.
• Every request and log identifies the effective API version.
• Migration docs include before-and-after examples and error behavior.
• Usage is measured before and during deprecation.
• Contract tests run for each supported version, including API pagination and error responses.

Versioning is successful when customers can upgrade on purpose. If a change requires them to discover it during an outage, it was not a migration plan.