API Migration

Use this workflow when deprecating an external or internal API, replacing REST with GraphQL or the reverse, migrating versions, or swapping vendors.

Pre-Investigation

1. Get the deprecation timeline.
2. Identify endpoint, webhook, and SDK surface area.
3. Map consumer blast radius across internal services, partners, and customers.

Investigation Phases

Phase	Focus	Evidence
Inventory	OpenAPI specs, clients, webhooks, SDK imports, docs.	Endpoint paths, payload schemas, auth headers.
Critical path mapping	Revenue-critical, data-loss-risk, and dependency flows.	Consumers, retries, idempotency, rollback needs.
Migration strategy	Complexity, priority, and rollout options.	Compatibility requirements, test effort, rate limits.

Checklist

• Complete endpoint inventory.
• Identify webhook consumers.
• Map authentication and authorization dependencies.
• Document rate limiting behavior.
• List external documentation commitments.
• Define backward compatibility requirements.
• Create rollback plan.
• Estimate testing effort.

Common Risks

• Webhook payload differences.
• Idempotency behavior changes.
• More restrictive rate limits.
• Feature gaps in the replacement API.
• SDK coverage differences.