The quiet death of the API redesign

In 2010, redesigning a major API was a moment. You announced a v2. You wrote a migration guide. You sent a sales team to your enterprise customers, and someone flew out to give a talk. The launch got a slot at the conference, a blog post on a Monday, and at least one mildly irritated Hacker News thread about backwards compatibility.

The redesign was, in a real sense, a product. It justified its own existence in roadmap terms: “we’ll ship v2 next quarter” was a fine OKR, and the v1-to-v2 migration story was a load-bearing narrative about progress.

You don’t see that anymore. Last quarter, four companies I follow shipped meaningful API changes — renamed resources, restructured auth, consolidated endpoints — and three of them did it as a routine flag flip in a changelog post. The fourth did it so quietly I found out from a junior engineer’s blog post about a debugging session.

This is, on balance, good. It is also the end of something.

What replaced the redesign

Three things, mostly.

First, versioning stopped being a competitive story. When v2 meant “we finally caught up to the leader,” the launch mattered. Now the leader is the leader because the API has been iteratively right for a decade; nobody catches up by relaunching. Stripe, the company most often held up as a model here, has been quietly refining the same surface for fifteen years. Their last “version” change was, I checked, a Tuesday afternoon commit.

Second, flags became a way to ship a redesign without naming it. This is the more interesting shift. A flag-gated redesign is, technically, a redesign. But because it’s framed as a configuration, it carries none of the political weight. No migration guide. No “breaking change” callout. No “we’re sorry” letter from the VP. Just a boolean in a console and a slow default-flip over six months.

Third — and this is the part I find interesting — engineers stopped wanting to be the person who shipped the redesign. I don’t have data on this, just an impression from talking to platform teams. The person who ships a v2 gets credit, but they also own the migration tickets for the next three years. The person who flips a flag gets a small win and never has to think about it again. In a culture that rewards shipping and punishes support load, the flag is the rational choice.

What gets lost

Here’s what I miss about the old way, though.

The old API launch was a forcing function for thinking. You had to write down what the new thing was and why it existed. You had to write the migration guide, which meant you had to understand the old thing. You had to give the talk, which meant you had to articulate the design decisions in a way that survived being said out loud in front of people who used the thing.

The flag has no such cost. It lets you ship a half-thought redesign and have it land as a routine change. The decisions stay in commit messages and Slack threads. The reasoning, such as it was, decays with the people who remember it.

I’ve started asking platform teams I work with: when you flip the flag, can you write the talk? Not because anyone will give it, but because writing it is the only way I know to test whether the redesign is actually coherent, or whether it’s a pile of local improvements that happen to be deployed together.

A small prediction

I think we’re going to see a counter-movement in the next few years — not back to version 2.0 announcements, but to a renewed practice of writing down why the API is the way it is, in a place that lives longer than a changelog.

Some companies are already doing this in the form of “design docs” published externally, or “API philosophy” pages. Most of them are bad. The good ones are good because they have a point of view. Stripe’s, historically, has been: “the API should be the boring, correct version of the thing you would have built if you had infinite time.” That’s a stance. It explains a thousand small decisions. Without it, you’re just guessing.

If you’re shipping API changes by flag right now — and most of us are — the question worth asking is not “did we ship it?” It’s “if a smart engineer joined the team next year and asked why the API looks like this, would we have a written answer?”

That’s it. That’s the whole redesign.