Most APIs don't get versioned because the business changed. They get versioned because the first design painted the team into a corner, and a v2 felt easier than untangling it. The fix is not a cleverer versioning scheme. It is designing so that almost every future change can be additive, which means you may never need a v2 at all, let alone a v3.
API versioning is the practice of publishing multiple contract variants (v1, v2) so old clients keep working while new ones get new behaviour. It solves a real problem, but every parallel version is a contract you test, document and support indefinitely.
Every version you publish is a promise you keep forever
Once a client integrates against v1, you own v1. Stripe has kept integrations working since 2011, and it manages that not by freezing the product but by treating old versions as thin transformation layers over one modern core. Their engineers write code for the current version only; a compatibility module downgrades responses for anyone pinned to an older date.
That is the pattern worth copying. If your team instead forks the codebase for v2, you fix every bug twice and answer support tickets for both, and the burden compounds with each live version. Postman's 2025 State of the API report found inconsistent documentation is the single biggest roadblock to collaboration for around two in five developers, and nothing produces inconsistent documentation faster than parallel versions drifting apart.
The chart is an illustrative model based on Stripe's versioning essay and Zalando's guidelines, but the shape matches what teams report: the gap is small in year one and painful by year three.
Design rules that make v2 unnecessary
A few habits, applied from day one, remove most reasons a v2 ever gets proposed.
Make changes additive by default. New optional fields, new endpoints and new enum values should never break a well-behaved client. Google's API improvement proposals spell out exactly what counts as backwards compatible, and it is a shorter list than most teams assume.
Tell clients to tolerate what they don't recognise. Publish a compatibility policy that says unknown fields must be ignored. GraphQL builds this in: its own best-practice guidance avoids versioning entirely because clients only ever receive the fields they ask for.
Never expose your database. The moment your response mirrors your tables, every schema migration becomes a contract negotiation. Model the API around the consumer's job, not your storage.
Get pagination, errors and identifiers right the first time. These are the three things teams most often redo in a v2. Cursor-based pagination, a structured error object and opaque string IDs cost nothing extra on day one and are near impossible to retrofit.
When you do need to break something
Sometimes a change is genuinely incompatible. Zalando's widely used REST API guidelines are blunt about the answer: avoid versioning where you can, and when you can't, prefer deprecating a field with a sunset date over stamping a new version on the whole API. Microsoft's public API guidelines take a similar line, requiring explicit deprecation windows and client notice rather than surprise removals.
The practical sequence is narrow deprecation first, dated version pinning second (the Stripe model), and a global v2 only as a last resort. This is also where an experienced review pays for itself. A short contract audit before launch, of the kind we run inside our backend development engagements, routinely catches the pagination and identifier mistakes that force versioning two years later.
FAQ
Should I put the version in the URL or a header?
If you follow the practices above, this matters far less than blogs suggest. A URL version (/v1/) is a fine safety valve you hope never to increment; Stripe's date-in-header approach suits frequent small changes but needs tooling.
Is GraphQL the answer to versioning?
It removes one class of problem, since clients select their own fields, but you can still break people by removing or repurposing fields. The discipline matters more than the protocol.
How long should I support a deprecated field?
Announce a sunset date, emit deprecation warnings in responses or headers, and give consumers a realistic migration window. For external APIs, six to twelve months is a common courtesy; internal APIs can move faster because you can see every caller.
Before your next API ships, run this checklist:
1. Confirm every response field exists because a consumer needs it, not because a table has it.
2. Adopt cursor pagination, opaque IDs and a structured error shape now.
3. Write down your compatibility policy, including how clients must treat unknown fields.
4. Define your deprecation process, with sunset dates and warning headers, before you need it.
5. Reserve a versioning mechanism as the last resort, and measure success by how rarely you use it.
If you'd like a second pair of eyes on a contract before it hardens, BeyondPixl Studio offers a fixed-scope API design review that stress-tests your schema, pagination and deprecation plan against five years of likely change. Book one before your first external consumer integrates, because that is the last cheap moment to fix it.