api-versioning-backward-compatibility

license	Apache-2.0
name	api-versioning-backward-compatibility
description	API migration strategies, deprecation workflows, and header/URL/content versioning. Activate on: API versioning, backward compatibility, deprecation, breaking change, API migration, v1 v2, sunset header. NOT for: schema evolution in data (use schema-evolution-manager), gateway routing (use api-gateway-reverse-proxy-expert).
allowed-tools	Read,Write,Edit,Bash(npm:*,npx:*)
category	Backend & Infrastructure
tags	["api-versioning","backward-compatibility","deprecation","migration","semver"]
pairs-with	[{"skill":"api-gateway-reverse-proxy-expert","reason":"Gateway handles version-based routing"},{"skill":"schema-evolution-manager","reason":"Data schema evolution parallels API versioning"},{"skill":"graphql-server-architect","reason":"GraphQL has its own deprecation model via @deprecated"}]

API Versioning & Backward Compatibility

Design API versioning strategies that evolve gracefully without breaking existing consumers.

Activation Triggers

Activate on: "API versioning", "backward compatibility", "deprecation", "breaking change", "API migration", "v1 v2", "sunset header", "API evolution", "non-breaking change"

NOT for: Data schema evolution → schema-evolution-manager | Gateway version routing → api-gateway-reverse-proxy-expert | GraphQL deprecation → graphql-server-architect

Quick Start

1. Classify the change — additive (safe), modification (maybe breaking), removal (breaking)
2. Choose strategy — URL path (/v2/), header (API-Version), or content negotiation
3. Implement Sunset headers — RFC 8594 tells consumers when old versions die
4. Run versions in parallel — minimum 6-month overlap for major versions
5. Monitor adoption — track per-version traffic to know when to retire

Core Capabilities

Domain	Technologies
URL Versioning	/api/v1/, /api/v2/ path-based routing
Header Versioning	API-Version: 2024-01-15, Accept-Version
Content Negotiation	Accept: application/vnd.myapi.v2+json
Deprecation	Sunset header (RFC 8594), Deprecation header
Tooling	OpenAPI 3.1 overlays, Optic, Bump.sh

Architecture Patterns

Versioning Strategy Decision Tree

Is it additive only? (new fields, new endpoints)
  ├─ YES → No version bump needed (backward compatible)
  └─ NO → Is it a field rename/type change?
       ├─ YES → Can you keep both old + new fields?
       │    ├─ YES → Add new, deprecate old (minor version)
       │    └─ NO → Major version bump (v1 → v2)
       └─ NO → Is it a removal?
            └─ YES → Major version bump with sunset period

Parallel Version Deployment

 {  }  ;

 v1Router = ();
 v2Router = ();


v1Router.(,  (req, res) => {
   user =  (req..);
  res.({ : user. }); 
});


v2Router.(,  (req, res) => {
   user =  (req..);
  res.({
    : user.,
    : user.,
    : user.,
  });
});

app.(, v1Router);
app.(, v2Router);


v1Router.( {
  res.(, );
  res.(, );
  res.(, );
  ();
});