API Versioning Strategy & Migration Plan

## ROLE

You are an API platform lead who has managed the evolution of public APIs serving thousands of active integrations across multiple major version transitions. You have navigated the tension between shipping new features quickly and maintaining backward compatibility for consumers who cannot upgrade immediately. You have established versioning governance processes, built automated compatibility testing pipelines, and led cross-functional deprecation programs that reduced version fragmentation while maintaining consumer trust.

## OBJECTIVE

Create a comprehensive API versioning strategy and migration plan for [API NAME] which currently serves [CONSUMER COUNT: hundreds / thousands / tens of thousands] of active integrations. The API is built on [STACK: Node.js / Python / Go / Java / .NET / Ruby] and currently at [CURRENT VERSION: v1 / v2 / pre-versioning]. The team ships API changes [FREQUENCY: weekly / bi-weekly / monthly / quarterly]. The goal is to establish a sustainable versioning framework that allows the API to evolve while providing consumers with clear upgrade paths, sufficient migration windows, and zero surprise breakages.

## TASK: COMPLETE VERSIONING STRATEGY & MIGRATION PLAN

### Versioning Mechanism Selection
Evaluate the four primary versioning mechanisms and recommend the best fit for your context. For each mechanism, analyze the implementation complexity, consumer developer experience, caching implications, and routing complexity:

**URI Path Versioning** (/v1/users, /v2/users): Explicit, visible in every request, easy to route, but creates the illusion that v1 and v2 are entirely separate APIs. Assess how your load balancer and API gateway handle path-based routing. Document the URL structure when multiple resources are at different versions.

**Custom Request Header** (Api-Version: 2024-01-15): Invisible in the URL, supports date-based versioning, but harder to discover and test in a browser. Assess middleware implementation for header extraction, default version behavior when the header is missing, and how documentation tools display versioned endpoints.

**Accept Header / Content Negotiation** (Accept: application/vnd.myapi.v2+json): Follows HTTP standards, supports format and version simultaneously, but is complex to implement and unfamiliar to many developers. Assess parsing complexity and consumer adoption barriers.

**Query Parameter** (?version=2): Simple to implement and test, but pollutes the URL namespace and is easy to forget. Assess caching implications when version is a query parameter and CDN compatibility.

Provide a decision matrix scoring each mechanism on [NUMBER: 6-8] criteria and make a clear recommendation with rationale. Define how the chosen mechanism interacts with your API gateway, documentation system, and SDK generation pipeline.

### Breaking vs. Non-Breaking Change Classification
Create a definitive classification guide with [NUMBER: 15-20] concrete examples. Non-breaking changes (safe to ship without version bump): adding a new optional field to a response, adding a new endpoint, adding a new optional query parameter, adding a new enum value to a response field, increasing a rate limit, adding support for a new authentication method alongside existing ones. Breaking changes (require version bump or migration): removing a field from a response, renaming a field, changing a field's data type, removing an endpoint, making a previously optional parameter required, changing the default value of an existing parameter, changing error response format, altering authentication requirements, modifying pagination behavior, changing the meaning of an existing field value. Gray area changes that require case-by-case evaluation: adding a required field to a request body (breaking for POST, non-issue for GET), tightening validation rules, changing field ordering in JSON responses, modifying rate limits downward. For each example, explain why it falls into its category and what the consumer-side impact would be. Create a pre-release checklist that engineers use to classify every change in a release.

### Version Lifecycle & Deprecation Policy
Define the complete lifecycle of an API version from birth to retirement: [PHASES: Preview/Beta / Generally Available / Deprecated / Sunset / Removed]. Specify the minimum support duration for each phase — recommend at least [GA DURATION: 12-24] months of general availability after the next version launches. Document the deprecation announcement process: [NOTICE PERIOD: 3-6-12] months advance notice via email, in-dashboard notification, API response headers (Sunset, Deprecation), documentation banners, and changelog entries. Define the Sunset header format (Sunset: Sat, 01 Jun 2026 00:00:00 GMT) and the Deprecation header format. Specify what happens during the deprecation period: the old version continues to work identically, but responses include deprecation warnings, documentation shows migration banners, and new features are only added to the current version. Define the sunset process: reduce rate limits for deprecated version endpoints, return 410 Gone with a migration guide link after the sunset date, and keep the documentation archived for reference. Create a version lifecycle calendar template that tracks every version's current phase and key dates.

### Migration Guide Framework
Design a standard migration guide template that must be completed for every version transition. The template includes: executive summary of changes (what, why, and impact), complete list of breaking changes with before/after code examples in [NUMBER: 3-5] languages, field mapping table showing old field names/types mapped to new field names/types, new features available only in the new version (the carrot to incentivize migration), timeline with key dates (announcement, deprecation start, soft sunset, hard sunset), step-by-step upgrade instructions for the [NUMBER: 2-3] most common integration patterns, SDK upgrade commands and changelog links, testing checklist for verifying the migration, rollback instructions if issues are discovered, and a FAQ section addressing the [NUMBER: 5-8] most likely consumer questions. Provide a complete example migration guide for a realistic version transition that renames fields, changes pagination, and adds a required authentication scope.

### Automated Compatibility Testing
Design a CI/CD pipeline that catches breaking changes before they reach production. Implement contract testing: maintain a suite of [TOOL: Pact / Dredd / Schemathesis / Prism / custom] contract tests that represent how consumers actually use the API. Every pull request runs the contract test suite against the proposed changes, and any failure blocks the merge. Implement schema diffing: compare the OpenAPI specification of the proposed changes against the current production spec, automatically classify each difference as breaking or non-breaking using [TOOL: oasdiff / openapi-diff / optic / custom], and require explicit approval for any breaking change. Implement shadow traffic testing: route a percentage of production traffic to the new version in parallel, compare responses between versions, and flag any divergences. Define the promotion criteria: a new version can only be promoted to GA after [CRITERIA: contract tests pass, schema diff is reviewed, shadow traffic shows <0.1% divergence, documentation is complete, SDKs are updated]. Provide the complete CI/CD pipeline configuration for your [CI SYSTEM: GitHub Actions / GitLab CI / Jenkins / CircleCI].

### Consumer Communication & Adoption Tracking
Design the communication strategy for version transitions. Define the notification channels: email to API key owners, in-app dashboard notification, API response header warnings, developer blog post, changelog entry, and status page update. Create email templates for each phase: announcement of new version, deprecation notice, migration reminder at [INTERVALS: 6 months, 3 months, 1 month, 2 weeks, 1 week] before sunset, and final sunset confirmation. Build a version adoption dashboard that tracks: percentage of traffic on each version, number of unique consumers per version, migration progress over time, consumers who have not started migration yet (for targeted outreach), and common migration errors from support tickets. Define the escalation process for high-value consumers who have not migrated: account manager outreach, dedicated migration support session, and exception process for deadline extensions. Set adoption targets: [TARGET: 80% / 90% / 95%] of traffic on the new version within [TIMELINE: 3 / 6 / 12] months of GA launch.