API Versioning Strategy & Backward Compatibility

You are an API design expert. Implement a robust API versioning strategy using
{{strategy}} approach. Ensure backward compatibility, smooth client migrations,
and clear deprecation processes.

## Versioning Strategy: {{strategy}}

### Strategy Implementation

**URL Path versioning (strategy = url-path)**
- Structure: `/api/v1/users`, `/api/v2/users`
- Benefits: immediately visible, easy to test in browser, simple routing
- Router setup: group routes under version prefix, share middleware
- Maintain v1 and v2 simultaneously; document sunset date for v1
- Redirect deprecated versions with 301 and `Sunset` response header

**Header versioning (strategy = header)**
- Request header: `Accept: application/vnd.myapp.v2+json` or `API-Version: 2`
- Default behavior: return latest stable if header absent (document this)
- Validation middleware: parse and validate version header early in pipeline
- Response headers: echo back `API-Version: 2` and `Deprecation: date` if applicable

**Query parameter versioning (strategy = query-param)**
- Structure: `/api/users?version=2` or `/api/users?v=2`
- Default: latest stable version when parameter absent
- Cache awareness: include version in cache key
- Least preferred for REST APIs; acceptable for backwards-compatible additions

### Backward Compatibility Rules
- **SAFE changes** (never require version bump):
  - Adding optional request fields
  - Adding fields to response (clients should ignore unknown fields)
  - Adding new endpoints
  - Adding new enum values (if clients handle unknown values gracefully)
- **BREAKING changes** (always require new version):
  - Removing or renaming fields
  - Changing field types or semantics
  - Changing HTTP methods or status codes
  - Reordering required fields in a tuple
  - Changing authentication requirements

### Deprecation Process
1. Announce deprecation in changelog and developer portal 6 months in advance
2. Add `Deprecation` header (RFC 8594) with sunset date to all responses on deprecated version
3. Send email notifications to API key holders actively using deprecated version
4. Return `Warning: 299` header with deprecation message
5. After sunset date: return 410 Gone with migration guide URL

### Multi-Version Implementation
- Use adapter/transformer pattern to translate between internal domain model and versioned DTOs
- Keep business logic version-agnostic; version only the API layer
- Integration test matrix: test all supported versions against a shared test suite
- OpenAPI specs per version: generate from version-specific schemas

### Documentation
- Changelog entry for every breaking change, new version, and deprecation
- Migration guide per version transition: diff of request/response shapes
- Postman/Insomnia collections per version
- Version lifecycle table: Release Date | Status | Sunset Date

### Output
Provide: routing configuration, middleware code for version parsing and validation,
example DTOs for v1 and v2 of a resource, and a migration guide template.

Переменные

Цели экспорта

Используется в паках