API Versioning Strategies That Don't Break Existing Clients

No universally correct choice. URI wins on simplicity. Headers win on cleanliness. Most teams at scale use a hybrid: major versions in the URI path, minor or date-based versions in headers. For most B2B APIs I'd start with URI path and only move to headers if the path-based approach creates routing problems.

The practical method works at any scale. Martin Fowler popularized it as "parallel change." Build the new lane before you close the old one.

Expand. Add the new field or behavior alongside the existing one. Nothing removed. Both coexist. If changing user_name to username, return both fields simultaneously.

Migrate. Communicate the change, update documentation, give consumers a timeline. Instrument the old behavior. Measure how many consumers still use it. You can't close a lane until you know it's empty, and knowing means telemetry, not hope.

Contract. Once telemetry confirms no active consumers depend on the old behavior (or the deprecation deadline has passed), remove it.

This works for REST, GraphQL, gRPC, and anything with a schema. It's the backbone of non-breaking API evolution. Teams that skip the migrate step (expanding and immediately contracting) are the ones generating 3 a.m. pages. The migration window is the point of the pattern.

Two HTTP headers formalize this. The Deprecation header (broadly adopted IETF draft) signals that an endpoint has been or will be deprecated. The Sunset header (RFC 8594) specifies the exact date it stops responding.

Together: machine-readable deprecation timeline. A consumer's HTTP client can detect these, log warnings, and trigger migration workflows without anyone reading a changelog.

Norms that have converged: six months notice minimum for standard endpoints, twelve for mission-critical ones. Include a Link header pointing to migration docs or the replacement endpoint. After sunset, return 410 Gone, not 404. A 410 tells the client "this was deliberately removed," which is easier to debug than a generic "not found."

The companies that do this well treat deprecation as a product launch in reverse. Stripe publishes detailed upgrade guides for every version. Twilio sends email campaigns months in advance. Zalando's open-source API guidelines specify deprecation as a required lifecycle phase.

I've seen this go wrong repeatedly. We once sent three emails, posted in the developer forum, and added banner warnings to the API dashboard. Six months later, 23% of consumers were still on the deprecated version. What finally worked was adding a Warning response header that their monitoring tools picked up automatically. Non-technical communication (emails, blog posts) supplements technical communication (headers, SDK warnings), but neither alone is sufficient.

The worst deprecation strategy is silence: removing an endpoint and hoping nobody notices.

A health-tech company whose Patient Records API served 340 external integrations (hospital EHR systems, insurance claim processors, telehealth platforms, analytics dashboards) needed to move from v1 to v2. Four years of inconsistent naming, a flat resource model, and authentication patterns that no longer met HIPAA requirements. They knew 340 integrations, many built by third-party vendors with their own release cycles, couldn't all migrate simultaneously.

They used expand-migrate-contract. Phase one stood up v2 endpoints alongside v1, both backed by the same data layer. No v1 endpoints removed or altered. Every v1 response got Deprecation headers with a date twelve months out and Link headers pointing to the v2 migration guide.

Phase two segmented consumers by call volume. The top 20 integrations (89% of traffic) received direct outreach: dedicated Slack channels, co-development sessions, and sandbox environments pre-loaded with their production data shapes in v2 format. The remaining 320 got email campaigns, documentation updates, and monthly "migration health" reports showing their v1 usage alongside v2 equivalents.

They built a daily-updated dashboard tracking v1 call volume per consumer. This was their lane-closure telemetry.

After nine months, 94% of traffic had migrated. The remaining 6% came from 47 integrations, 31 of which turned out to be abandoned (no activity beyond automated health checks from forgotten cron jobs). They contacted the remaining 16 active consumers, extended their deadline by three months, and offered engineering support.

At month fourteen, they set v1 to return 410 Gone with the v2 equivalent URL in the response body. Two integrations broke. Both were fixed within hours because the 410 told them exactly what happened and where to go. The post-mortem identified consumer-segmented outreach and daily telemetry as the two decisions that made the project survivable.