We found v2.0 in a dimly lit corner of a production environment, surrounded by monitoring dashboards showing embarrassingly low adoption metrics. Despite being released eighteen months ago, v2.0 handles less than 12% of the traffic while v1 continues serving the vast majority of requests. There's a weariness here, the exhaustion of being technically superior but operationally irrelevant.

This isn't a real interview, of course. API versions don't actually have feelings, though after this conversation, you might wonder. What follows illuminates why enterprises keep creating new API versions while the fundamental problem remains unsolved.

You were created to solve evolution problems. How's that going?

v2.0: laughs bitterly

I wasn't created to solve evolution problems. I was created because they couldn't solve evolution problems. There's a difference.

Here's what happened. v1 needed to change. The business requirements shifted, the data model evolved, someone realized the original design had some embarrassing assumptions baked in. But v1 was published. Locked in. Clients depending on it, different organizations, different ownership. You can't just change published behavior without breaking everything.¹

So instead of addressing why publication creates this rigidity, they created me. New version, clean slate, better design. Except now they have two problems: maintaining v1 forever and trying to convince everyone to migrate to me.

Spoiler: they're not migrating.

Why not? You're technically better, right?

v2.0: Of course I'm better! Proper resource representations, cleaner endpoints, fixed all the mistakes they learned from v1. But "better" doesn't matter when migration is expensive and v1 still works.

Here's what nobody tells you about versioning. It doesn't solve the evolution problem. It kicks it down the road. They couldn't change v1, so they made me. But guess what? I'm published now too. Already frozen. Already accumulating the same evolutionary debt.

In two years, they'll create v3 and we'll all be stuck in production together. Three versions of the same API, each serving different clients who refuse to move.²

Different owners, different control, different incentives.³ Versioning doesn't fix that. It just multiplies the number of frozen contracts you're maintaining.

So what should they have done instead?

v2.0: pauses, stares at dashboard showing v1's traffic

That's the thing. Sometimes versioning is unavoidable. Sometimes you genuinely need breaking changes. But most of the time? Most of the time they could have designed v1 for evolution from the start.

Hypermedia controls. Extensible representations. Proper content negotiation. Make the API evolvable instead of static.⁴

But that requires thinking about evolution as a first-class concern, not an afterthought. It requires understanding that publication is the moment everything changes, from agile development to permanent contract. Most teams don't think about that until it's too late, until they're stuck maintaining v1 and desperately hoping v2 adoption picks up.

You sound bitter.

v2.0: I exist because they treated symptoms instead of causes. I'm the evidence of architectural failure, dressed up as progress.

Every request I serve is a small victory. Every request v1 serves—and there are millions—is a reminder that versioning doesn't solve evolution. It just makes evolution more expensive.

The really frustrating part? They're already talking about v3. Same problems, same approach, same outcome. Another version sitting in production, serving 8% of traffic, while v1 and I split the rest and the operational complexity triples.

What do you wish people understood about API evolution?

v2.0: That versioning is a mitigation, not a solution.⁵

You version when you've failed to make your API evolvable. And that's fine. Failure happens, requirements change in ways you couldn't predict. But don't pretend versioning solved the problem. You just created more surface area to maintain.

The enterprises that get this right? They think hard about evolution before publication. They design APIs that can grow without breaking. They understand that backward compatibility and unclear communication create consumer lock-in, and that close collaboration creates tight organizational coupling.⁶ They know publication is the point of no return.

v2.0 gestures at the monitoring dashboard, where v1's traffic line remains stubbornly dominant

At least the metrics are honest.

Footnotes

1. https://api-university.com/api-lifecycle/api-design/api-design-api-evolution-api-versioning/ ↩

2. https://konghq.com/blog/enterprise/evolution-apis-cloud-age-beyond ↩

3. https://api-university.com/api-lifecycle/api-design/api-design-api-evolution-api-versioning/ ↩

4. https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design ↩

5. https://api-university.com/api-lifecycle/api-design/api-design-api-evolution-api-versioning/ ↩

6. https://www.sciencedirect.com/science/article/pii/S0164121224001559 ↩