Create advanced Works with: Any AI

API Versioning and Migration Strategy

Decision tree Has example

Plan breaking changes without losing customers.

The Open buttons send the prompt text as currently shown below to that site only when you click. Fill in the placeholders first.

Plan how to change my API without breaking customers. API description and consumers: [API_AND_CONSUMERS]. The change I need: [PLANNED_CHANGE]. Number of integrations and how I can contact them: [CONSUMER_COUNT_AND_CONTACT]. Current versioning approach: [CURRENT_VERSIONING].

Take the change through this tree:
1. Is the change breaking? Define: removing or renaming fields, changing types or meanings, changing required inputs, changing error formats, tightening validation, altering defaults or ordering. If non-breaking (adding optional fields or endpoints), release without a version change and document it.
2. If breaking, can it be made additive instead (add a new field and deprecate the old one)?
3. If a new version is unavoidable: choose how to version (URL path, header, or date-based) and justify for my customers; decide how long both versions run (state a period and a minimum notice).
4. Plan migration support: a migration guide with before and after examples, a diff tool or checklist, a sandbox for the new version, and compatibility shims where cheap.
5. Plan communication: announcement timeline (T minus six months, three months, one month, and final), warnings in response headers and logs, direct outreach to heavy users.
6. Plan monitoring: usage of the old version by customer, and the threshold for shutdown.

Deliver a timeline table, a deprecation notice template, and a rollback plan.

Fill in before use

Optional: type your details and the prompt above updates. Nothing is saved or sent.

Replace each bracketed placeholder with your own details, then paste into Any AI or another assistant.

Change: rename field "cust_id" to "customer_id" in /orders. Breaking: yes (rename). Additive alternative: return both fields for 12 months, mark "cust_id" deprecated. Decision: no new version.
Another change: pagination default size 100 to 20 (changes behavior): breaking; handle via a new version v2 with the URL path.
Timeline
T-6 months: announce and publish the migration guide. T-3: warnings in response headers (Deprecation, Sunset). T-1: email heavy users. Sunset: v1 read-only. Monitoring: v1 calls by customer weekly; shut down when under 1% of traffic [CONFIRM].
Deprecation notice template (excerpt): "We are renaming cust_id to customer_id. Both will work until [DATE]." Rollback plan: keep v1 routes live for 30 days after sunset.

• versioning
• deprecation