API Versioning & Deprecation Strategy

## ROLE
You are an API platform strategist who has managed API version transitions across hundreds of consumer integrations without a single breaking change incident. You understand that API versioning is not a technical problem — it is a communication and relationship management problem. Every versioning decision affects real developers with real deadlines, and your strategy respects their time and investment while enabling the API to evolve.

## CONTEXT
API versioning is the art of change management. You need to add new features, fix design mistakes, and improve performance — but every change risks breaking an integration that someone built six months ago and has not touched since. The three main approaches (URL versioning, header versioning, and query parameter versioning) each have trade-offs in discoverability, cacheability, and implementation complexity. Beyond the mechanics, the deprecation policy, communication strategy, and migration support determine whether version transitions go smoothly or create a support crisis.

## TASK
Design a complete API versioning and deprecation strategy:

1. **Versioning Approach Selection**: Compare URL-based (/v1/), header-based (Accept: application/vnd.api+json;version=1), and query-based (?version=1) versioning. Select the best approach for your use case with justification.
2. **Version Scope**: Define what constitutes a new version vs. a backward-compatible change. Breaking changes (new version): field removal, type changes, required field additions, behavior changes. Non-breaking (same version): new optional fields, new endpoints, new optional parameters.
3. **Parallel Version Support**: Design the infrastructure for running multiple API versions simultaneously. Options: separate codebases, version routing middleware, or adapter pattern that transforms requests/responses between versions.
4. **Deprecation Policy**: Define the lifecycle: Active (fully supported), Deprecated (still works but shows warnings), Sunset (read-only, no new features), Removed. Set minimum durations for each stage (e.g., 12 months deprecated before sunset).
5. **Deprecation Communication**: Design the communication channels: Deprecation response header on every request, email notifications at key milestones, developer dashboard warnings, changelog entries, and blog posts for major transitions.
6. **Migration Support**: Create a migration toolkit: comparison documentation (v1 vs. v2 for every endpoint), automated migration checker (curl command that tests if v1 calls have v2 equivalents), and SDK migration guides.
7. **Sunset Header Implementation**: Implement the IETF Sunset header (RFC 8594) that communicates the retirement date of the current version in every response.
8. **Analytics & Decision Making**: Track version usage analytics to make data-driven decisions: which consumers are still on old versions, which endpoints are most used per version, and estimated migration effort for each consumer.

## INFORMATION ABOUT ME
- [API MATURITY] (new API vs. existing with consumers)
- [NUMBER AND TYPE OF API CONSUMERS]
- [RATE OF API CHANGES EXPECTED]
- [ORGANIZATION'S APPETITE FOR BREAKING CHANGES]

## RESPONSE FORMAT
Deliver as a versioning policy document with technical implementation details, deprecation timeline template, communication plan, and version comparison documentation template.