⚡AgentSkills
⚙️ Backend Engineering · API Design

Migrate API versions without breaking clients

Run two versions in parallel, observe usage, and sunset safely with real telemetry.

advanced~40 minBackend EngineersAPI DevelopersPlatform Engineers

Steps

  1. 1Ship vN+1 alongside vN behind the same gateway; no big-bang cutover
  2. 2Tag responses with version header so bug reports are attributable
  3. 3Instrument per-client version adoption; email laggards with deadlines
  4. 4Keep a contract test suite pinned per version in CI
  5. 5Announce sunset twice: 90 days and 14 days before shutdown
  6. 6Return 410 with migration guide URL after the date, not silent 404s

Common Pitfalls

  • ▲Silent breaking changes hidden inside 'minor' fixes
  • ▲Sunsetting before the top-3 consumers migrate

Commands

Install with skills CLI
$ npx skills add aniruddhaadak80/skills --skill api-design-api-versioning-migration
Install globally
$ npx skills add aniruddhaadak80/skills --skill api-design-api-versioning-migration -g

Tags

#versioning#migration#backend-engineering#api-design

Related skills

Model REST resources without leaking internals (GraphQL flavor)foundation

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

⚙️ Backend Engineering·~30m
Open →
Model REST resources without leaking internals (gRPC services)foundation

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

⚙️ Backend Engineering·~30m
Open →
Make writes safe with idempotency keysintermediate

Accept retried mutations gracefully by keying operations so duplicates return the original result.

⚙️ Backend Engineering·~30m
Open →