# Migrate External API

> Phased migration of a third-party API client — new client alongside the old, reads before writes, a disagreement metric before cutover. Use when replacing or upgrading a provider SDK.

- Skill: `ai-driven-dev/migrate-external-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ai-driven-dev/migrate-external-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-driven-dev/migrate-external-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ai-driven-dev (https://skillmd.com/u/ai-driven-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ai-driven-dev/migrate-external-api

---


# Migrate an external API

Same shape every time, on five clients now. Written down after the third one,
where I improvised and shipped a cutover I could not roll back.

## The rule that produces every step below

**Every phase ships alone and reverts alone.** If a phase cannot be reverted by
a deploy, it is two phases.

## Steps

1. **Read the provider's changelog end to end.** Not the migration guide — the
   changelog. The guide tells you what they want you to change; the changelog
   tells you what actually changed.
2. **List the semantic differences**, not the signature differences. Retries,
   idempotency, pagination, error taxonomy, rate limits. Signature changes are
   found by the type checker; semantic changes are found in production.
3. **New client alongside the old, unused.** Ships on its own, reverts on its own.
4. **Reads first.** A wrong read is visible. A wrong write is not.
5. **A disagreement metric before the write cutover.** Count the cases where old
   and new disagree. Cut over when it is flat at zero for a week, not when the
   tests pass.
6. **Writes.** One real transaction in test mode, checked by hand, before the
   phase is called done.
7. **Remove the old client** in a later release, never the same one.

## Stop conditions

- The disagreement metric is not flat → do not cut over, whatever the deadline.
- The phase touches a file another track is rewriting → wait, do not merge.
- The provider's deprecation date moves closer than the remaining phases → say
  so to the client, in writing, the day you notice.

## What this procedure does not cover

Anything with a data migration attached. That is `schema-migration`, and it is
a different set of rules.