What this prompt does
This prompt directs the AI to act as a senior API architect and design a versioning strategy that won't break clients, with working code rather than pseudocode. You provide the [stack], the current [clients], and the [cadence]. It returns a versioning decision (URL prefix versus header), rules for additive versus breaking changes, a deprecation window with Sunset and Deprecation headers and a changelog policy, a worked v1-to-v2 migration for one endpoint, server code routing both versions, and a short stability policy doc clients can read.
The structure works because a careless breaking change loses a customer's trust overnight, and the politics of "when can we remove v1" cause more pain than the code. Locking the deprecation window and sunset headers before v2 ships stops clients integrating against a moving target. [stack] shapes the routing code, [clients] frames who you must not break, and [cadence] informs how long deprecation windows realistically need to be.
When to use it
- You're about to ship v2 and want a strategy that protects existing clients.
- You need to decide URL-prefix versus header-based versioning with a clear rationale.
- You want explicit rules for what counts as additive versus breaking.
- You need a deprecation window with Sunset and Deprecation headers.
- You want a worked v1-to-v2 migration for one endpoint, request and response.
- You need a short stability policy that external clients can actually read.
Example output
You get a versioning policy doc plus runnable example code: a versioning decision between URL prefix (/v1) and header-based, with the tradeoff that decides it; rules for additive versus breaking changes and which trigger a new major version; a deprecation window with Sunset and Deprecation headers and a changelog policy; a worked v1-to-v2 migration example for one endpoint covering request and response; server code in [stack] routing both versions cleanly; and a short policy doc clients can read to know what "stable" means.
Pro tips
- Nail the deprecation window in step 3 first — the politics of when you can remove v1 cause more pain than the code, so lock the timeline and sunset headers before v2 ships.
- Set
[clients]honestly, including third-party integrators, since they're the ones who can't redeploy on your schedule and dictate how generous the window must be. - Use
[cadence]to size the deprecation window realistically; a bi-weekly release train still needs a long sunset for external consumers. - Match
[stack]to your real framework so the dual-version routing code drops in cleanly rather than needing translation. - Pick URL-prefix or header versioning based on your clients' tooling, and write down the single tradeoff that decided it for future maintainers.
- Publish the stability policy doc where clients will see it, so nobody integrates against an endpoint you're about to deprecate.
