Enterprise prospects were asking hard questions about authentication patterns, rate limits, and change management. The product team could not ship net-new capabilities cleanly on top of an under-documented, organically grown API surface.
Strategy
We recommended a new major version rather than silent breaking changes. That sounds obvious, but it requires discipline: parallel operation, clear deprecation timelines, and tooling so integrators could test against a sandbox.
Execution
We mapped existing endpoints to the new design, introduced OpenAPI as the contract source of truth, and built migration guides with request/response diffs. Internal services were refactored behind facades so the core domain did not fork.
Change management
Partner communications went out in waves: design partners first, then general availability with a 9-month sunset for legacy routes. Support metrics and error rates were monitored daily during the first weeks of each wave.
Takeaway
API modernisation is as much product management as engineering. When done well, it unlocks sales cycles and reduces support load—without the reputational damage of a chaotic cutover.