74 lines
2.5 KiB
Markdown
74 lines
2.5 KiB
Markdown
# 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
|