What this prompt does
This prompt plans a full migration from [current_api] to [target_api] rather than just swapping a version number. It asks for a versioning strategy ([versioning_approach]) with parallel running, a backward-compatible-changes checklist, a migration plan for the specific [breaking_changes] you list, a deprecation timeline with a communication plan, a client SDK migration guide, feature flags for gradual rollout, API-gateway routing rules for percentage-based traffic shifting, data migration for schema changes, monitoring that compares v1 versus v2 usage, and a rollback plan.
The structure works because the riskiest part of an API migration isn't writing v2 — it's not breaking the integrations already depending on v1. Running both versions in parallel, shifting traffic by percentage, and keeping a rollback ready means you can validate v2 against real usage before committing. Naming your actual [breaking_changes] (renamed fields, removed endpoints, changed auth) forces the plan to address each one explicitly instead of hand-waving "some things will change."
When to use it
- You're moving from
[current_api]to a new major version and have live integrations you can't break. - You need a defensible deprecation timeline and client-facing communication templates.
- You're introducing breaking changes and want each one mapped to a migration step.
- You want gradual rollout via feature flags and percentage-based traffic shifting, not a hard cutover.
- You need monitoring to compare error rates and latency between the old and new versions.
- You're being asked "what's the rollback plan?" and need a real answer before shipping.
Example output
Expect a migration timeline, a checklist separating backward-compatible from breaking changes, client-communication templates for the deprecation, an SDK migration guide, gateway routing rules for traffic shifting, and a compatibility test suite that validates both [current_api] and [target_api] together. The monitoring section defines which signals (usage, errors, latency) to watch per version so you know when v2 is safe to make the default.
Pro tips
- List your real
[breaking_changes]precisely — renamed fields, removed endpoints, changed auth flow — because vague inputs produce a vague plan that misses the exact thing that breaks clients. - Choose
[versioning_approach]to match your stack: URI versioning is the most visible and cache-friendly, but header-based versioning may fit better if you already route that way. - Keep parallel running for as long as your slowest integrator needs; the deprecation timeline should be driven by client behavior, not an arbitrary date.
- Use the percentage-based routing rules to shift traffic in small increments and watch the per-version monitoring before each bump.
- Treat the rollback plan as mandatory and test it; a rollback you've never exercised is a hope, not a plan.
- Tailor the communication templates to your audience — internal teams and external partners need different notice and detail.
