Orderly API Evolution: How to Break APIs Without Breaking Trust (www.davidpoll.com)

A veteran API steward proposes “Orderly API Evolution”: a pragmatic framework for evolving APIs without eroding developer trust, drawn from running Firebase’s API Council and building MCP (Model-Connected Platform) servers. The piece argues SemVer is necessary but insufficient — Hyrum’s Law and overloaded interfaces mean many observable behaviors get depended on, and edge cases (error strings, logs, documented-internal surfaces, transitive deps) require judgment, not pure automation. Practical tactics that worked at scale include explicitly separating internal vs. external interfaces (allowing independent versioning), coordinating annual breaking releases across product portfolios, publishing deprecation SLAs while flexibly extending them based on real usage, monitoring adoption in real time, sequencing backend and client deprecations together, preview blackouts to accelerate migration, and making new APIs genuinely better to incentivize upgrades. MCPs and agentic coding complicate versioning further because different audiences (end users, coding agents, agent builders, direct API callers) care about different stability properties: tool signatures, fuzzy capabilities, or mental models. This raises questions like whether renaming a parameter is “breaking” if agents can adapt, and whether deprecated tools should be flagged in ways agents understand. The author suggests expanding tooling: machine-readable migration instructions, agents that auto-migrate or fall back, and possibly multiple versioning schemes (capability vs. interface stability). Bottom line: evolving APIs in an AI era requires data-driven judgment, explicit boundaries, coordinated policies, and new agent-aware tooling to preserve trust while enabling progress.