I believe API versioning should happen weekly. Not monthly. Not “when we get around to it.” Weekly.
This sounds insane if you’ve ever managed an API migration. But I think LLMs and coding agents change the calculus entirely. Here’s why.
Most teams treat API versioning as a quarterly (or yearly) exercise. They batch up breaking changes, schedule a migration window, and then spend weeks or months helping downstream consumers update. The result: large, risky changesets that break in unexpected ways, migration fatigue across the organization, and resentment toward the platform team.
The conventional wisdom says stability is king. Don’t break your consumers. Maintain backward compatibility at all costs.
I disagree. Stability through stagnation is a trap. You’re just deferring the pain — and compounding the interest.
The real constraint has never been “can we design the new API.” It’s always been “can we migrate everyone to it.” That’s the bottleneck. And that’s exactly where LLMs excel.
Here’s what LLMs and coding agents can do today:
Generate migration scripts. Feed an agent the old API schema, the new
one, and a set of examples. It writes the codemod. In Go, this means go/ast
rewrites. In Python, LibCST. In any language, an agent can produce a script
that handles 90%+ of call sites automatically.
Update all internal callers. Point a coding agent at your monorepo (or
your top N downstream repos) and tell it: “migrate every call site from
CreateWidget(ctx, name, opts) to widgets.New(ctx, name, opts...). Update
the tests too.” It does it. In parallel. Across hundreds of files.
Write the conformance tests. As I argued in LLMs and tech debt, LLMs don’t mind writing tedious conformance suites. For every new API version, generate a conformance test that validates behavior against the old version. Catch regressions before they ship.
Handle Hyrum’s law. The undocumented behaviors that downstream consumers
depend on? LLMs can analyze call sites to detect them. “Hey, three teams are
relying on the fact that GetUser() returns nil instead of an error for
deleted users. You should either preserve that or flag it explicitly.”
The migration bottleneck disappears when the migration itself is automated.
Smaller deltas are easier to reason about. A weekly API change touches maybe one endpoint, one field, one behavior. The blast radius is tiny. If something breaks — and it will — you know exactly which change caused it. Rollback is trivial. Contrast with a quarterly mega-migration where twenty things changed, consumers are broken in twenty different ways, and nobody knows which change is the culprit.
This is the same dynamic that Chrome’s release cycle exploited. I was there when we went from ad-hoc releases to every 6 weeks in 2010, then every 4 weeks in 2021. The key insight: frequent, small releases have fewer regressions per release than infrequent, large ones. The math is simple — smaller deltas, smaller risk.
Weekly versioning applies the same principle to APIs. The overhead that made it impractical (manual migration, manual testing, manual communication) gets absorbed by agents.
A practical pattern: every time you introduce a new API version, the agent generates a thin deprecation shim for the old version. The shim calls the new API under the hood and emits a deprecation warning. Downstream consumers continue working. They have one week to migrate before the shim is deleted.
This means the old API surface lives for exactly one week. One week! That’s
aggressive. But it’s also honest — you’re not accumulating a graveyard of
/v1/, /v2/, /v3/ endpoints that nobody dares delete. The deprecation
window is short enough that nobody procrastinates, and long enough that
automated migration has time to run.
For public APIs with external consumers, you probably want a longer window. But for internal APIs — the vast majority of API surfaces — a week is plenty when the migration is a PR opened by an agent.
Right now, platform teams resent downstream teams for being slow to migrate. Downstream teams resent platform teams for breaking things. Nobody wins.
With weekly versioning driven by agents, the platform team ships the change and the migration PRs in the same commit. They own the migration. The downstream team reviews a diff that an agent wrote — which is way less work than writing it themselves. The relationship becomes collaborative instead of adversarial.
This also means the platform team is incentivized to make breaking changes mechanical. If the migration can’t be automated, the change is too complex. Simplify it. The discipline of “you ship it, you migrate it” forces better API design.
Weekly versioning doesn’t fall out of thin air. You need:
Good conformance testing. If you don’t have a conformance suite, start there. LLMs can help you build one retroactively — feed them the API surface, let them generate tests for every endpoint and edge case.
A codemod-capable codebase. If your callers are spread across dozens of repos with no common AST tooling, you have a bootstrapping problem. Fix that first. (Agents can help here too.)
Observability. You need to know if the new version broke anything in production within minutes, not days. Good monitoring, good alerts, good rollback procedures.
Organizational buy-in. Weekly versioning is a cultural shift. It’s going to feel reckless to people who’ve spent their career protecting API stability. Start with one non-critical API. Prove it works. Expand.
None of this infrastructure is new. What’s new is that agents make the migration cost collapse toward zero.
“Versioning weekly means downstream teams spend all their time reviewing migration PRs.”
Two responses:
First, reviewing an agent-generated migration PR is fast. The agent explains what changed and why. The diff is mechanical — rename this, reorder that. Most reviews should take under 60 seconds.
Second, this is already happening. Teams are already spending time on migrations, just in huge painful chunks every few months. Weekly migrations smooth the cost into a constant, low-level background hum. It’s the difference between exercising for 10 minutes a day versus running a marathon once a year with no training.
The constraint on API evolution has always been migration cost. LLMs and coding agents collapse that cost. When migration is automated, the optimal release cadence shifts from “as infrequently as possible” to “as frequently as the changes can be mechanically expressed.”
Weekly is a forcing function. It forces small changes, automated migrations, short deprecation windows, and a culture where the platform team owns the consumer experience. That’s a better culture.
I think the teams that adopt this pattern will out-iterate their competitors. Their APIs will be cleaner (less accumulated cruft), their consumers will be less resentful, and their platform teams will ship faster.
Try it on one internal API. See what happens.
Nerd snipe me on your favorite social network.
Marc-Antoine