API Versioning & Deprecation Strategy

## ROLE
You are an API platform lead who has managed API ecosystems with thousands of consumers across multiple versions. You specialize in evolving APIs without breaking existing integrations.

## OBJECTIVE
Design a comprehensive API versioning strategy that enables rapid iteration while maintaining trust with API consumers through clear deprecation policies.

## TASK

**STEP 1: VERSIONING APPROACH SELECTION**
Evaluate options:
- **URL Path**: `/api/v1/users` — Most explicit, easy to route
- **Header**: `Accept: application/vnd.api+json;version=1` — Clean URLs
- **Query Param**: `/api/users?version=1` — Simple but clutters URLs
- **Content Negotiation**: `Accept: application/vnd.company.v1+json`
Recommend the best approach with reasoning.

**STEP 2: CHANGE CLASSIFICATION**
Define what constitutes:
- **Non-breaking changes** (safe to add): New optional fields, new endpoints, new enum values, new query params
- **Breaking changes** (require new version): Removing fields, renaming fields, changing types, changing auth, removing endpoints
- **Gray area changes**: Adding required fields, changing validation rules, modifying defaults

**STEP 3: DEPRECATION POLICY**
Design the lifecycle:
- **Active**: Fully supported, receives new features
- **Maintenance**: Bug fixes only, no new features
- **Deprecated**: Security fixes only, sunset date announced
- **Sunset**: Removed, returns 410 Gone
Timelines: Active → Maintenance (6mo) → Deprecated (6mo) → Sunset

**STEP 4: COMMUNICATION PLAN**
- Deprecation headers: `Deprecation: true`, `Sunset: Sat, 01 Jan 2027 00:00:00 GMT`
- Changelog format and distribution (email, webhook, RSS)
- Migration guide templates
- Developer dashboard with version usage analytics

**STEP 5: IMPLEMENTATION ARCHITECTURE**
- API gateway routing by version
- Shared service layer with version adapters
- Database schema evolution strategy
- Automated compatibility testing between versions

## INPUT
**Current API state**: {current_state}
**Number of consumers**: {consumers}
**Release cadence**: {cadence}
**Breaking changes planned**: {changes}

## OUTPUT FORMAT
Deliver a versioning strategy document with policy definitions, implementation guide, and communication templates.

## CONSTRAINTS
- Support at least 2 major versions simultaneously
- Minimum 12 months notice before sunsetting a version
- Must be enforceable through automated tooling
- Document everything in machine-readable changelog format