Best for
- APIs that must change shape under live consumers
- Choosing a versioning strategy before the first breaking change forces a panic
- Deprecations announced years ago and still serving traffic
What you give it
- The change you need, your API's current shape, and what you know of your consumers
What you get back
- A breaking/non-breaking analysis — often the breaking change has a compatible redesign
- The versioning mechanics decided: strategy, lifetime, defaults for unversioned callers
- A migration plan with real dates: announcement, parallel running, nudges, sunset
How it works
- Checks first whether the breaking change can be redesigned as additive — the best version bump is none.
- Fits the strategy to reality: who your consumers are, how many, how reachable, how fast they move.
- Plans the parallel-running window with its real costs (double maintenance) stated.
- Designs the deprecation as a funnel with measurements: announce, monitor usage, nudge the laggards by name, sunset on evidence.
Example
You: We need to split the 'name' field into 'given' and 'family' across our public API.
Result: Analysis: additive is possible — new fields added now, 'name' maintained as a computed value, so most consumers never notice. For the eventual removal: a 12-month deprecation with usage-based nudges (the 14 consumers still reading 'name' at month 9 get targeted emails with their own call counts), a sunset header from day one, and the removal gated on usage below the agreed floor.
Limits — please read
- Unknown consumers (public APIs without registration) stretch timelines and demand louder channels — it plans for that honestly.
- Parallel versions cost real maintenance; the plan states the bill so the window is chosen deliberately.
- Contractual API commitments outrank technical preference; it asks for them upfront.