Kordant/tasks/web-production/28-api-versioning.md

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