# 28. API Versioning & Deprecation Strategy

meta:
  id: web-production-28
  feature: web-production
  priority: P2
  depends_on: []
  tags: [api, stability, mobile]

objective:
- Establish API versioning and deprecation strategy to support mobile app updates without breaking existing clients

deliverables:
- API versioning scheme
- Deprecation policy documentation
- Backward compatibility testing
- Mobile client version tracking

steps:
1. Implement API versioning:
   - Current: tRPC v10 (consider upgrade to v11)
   - Add version header or URL prefix for breaking changes
   - Version format: v1, v2, etc.
   - Mobile apps send X-API-Version header
2. Create deprecation policy:
   - Document in docs/API_VERSIONING.md
   - Breaking changes only in major versions
   - Support previous version for minimum 6 months
   - Announce deprecations 3 months in advance
   - Sunset dates for old versions
3. Add version negotiation:
   - Backend supports multiple tRPC router versions
   - Route to correct router based on version header
   - Default to latest for web clients
4. Track client versions:
   - Log app version from User-Agent or X-Client-Version
   - Dashboard showing active client versions
   - Alert when old versions still in use near sunset
5. Add compatibility tests:
   - Test all mobile app versions against current API
   - Automated compatibility matrix
   - Breaking change detection in CI
6. Document API changes:
   - Changelog for all API modifications
   - Migration guides for major versions
   - Breaking vs non-breaking classification

tests:
- Unit: Test version routing
- Integration: Test old client with new API
- Compatibility: Verify mobile app versions work

acceptance_criteria:
- API versioning scheme documented and implemented
- Mobile apps send version header in all requests
- Backend supports at least 2 API versions simultaneously
- Deprecation policy published and followed
- 6-month support window for old versions
- Client version tracking dashboard active
- Compatibility tests passing for all supported versions
- Changelog maintained for all API changes

validation:
- Mobile app sends X-API-Version: 1 → receives v1 responses
- Deploy v2 changes → v1 clients continue working
- Check dashboard → active client versions visible
- Review changelog → all changes documented

notes:
- tRPC v10 to v11 is a breaking change — plan migration carefully
- Mobile apps may take weeks to update — long support windows needed
- Consider using feature flags instead of versioning for minor changes
- Track iOS and Android app versions separately