--- name: api-versioning-deprecation-planner description: Plans safe API evolution with versioning strategies, client migration guides, deprecation timelines, and backward compatibility considerations. Use for "API versioning", "deprecation planning", "API evolution", or "breaking changes". --- # API Versioning & Deprecation Planner Safely evolve APIs without breaking existing clients. ## Versioning Strategies ### URL Versioning (Recommended) ``` /api/v1/users /api/v2/users ``` **Pros:** Clear, easy to route, simple to document **Cons:** URL pollution with many versions ### Header Versioning ``` GET /api/users Accept: application/vnd.api.v1+json ``` **Pros:** Clean URLs **Cons:** Harder to test, less visible ### Query Parameter ``` /api/users?version=1 ``` **Pros:** Easy to implement **Cons:** Not RESTful, easy to forget ## Deprecation Timeline ```markdown # API Deprecation Plan: v1 → v2 ## Timeline (6 months) ### Month 1: Announcement - [ ] Publish deprecation notice in changelog - [ ] Email all API consumers - [ ] Add deprecation headers to v1 responses - [ ] Update documentation with migration guide ### Month 2-4: Migration Period - [ ] v2 fully available - [ ] Both v1 and v2 supported - [ ] Track v1 usage metrics - [ ] Offer migration support ### Month 5: Final Warning - [ ] Email reminder to remaining v1 users - [ ] Increase deprecation warning visibility - [ ] Offer 1-on-1 migration help ### Month 6: Sunset - [ ] Disable v1 endpoints - [ ] Return 410 Gone with migration instructions - [ ] Monitor for issues ``` ## Deprecation Response Headers ```http HTTP/1.1 200 OK Deprecation: true Sunset: Sat, 31 Dec 2024 23:59:59 GMT Link: ; rel="alternate" Warning: 299 - "This API version is deprecated. Migrate to v2 by Dec 31, 2024" ``` ## Breaking vs Non-Breaking Changes ### Non-Breaking (Safe) ✅ Adding new endpoints ✅ Adding optional request parameters ✅ Adding fields to responses ✅ Adding new response status codes ✅ Making required fields optional ### Breaking (Requires New Version) ❌ Removing endpoints ❌ Removing request parameters ❌ Removing response fields ❌ Changing field types ❌ Making optional fields required ❌ Changing authentication ## Migration Guide Template ```markdown # Migration Guide: API v1 → v2 ## What's Changing ### Authentication **v1:** API Key in query param ``` GET /api/v1/users?api_key=xxx ``` **v2:** Bearer token in header ``` GET /api/v2/users Authorization: Bearer xxx ```` ### Response Format **v1:** Snake case ```json {"user_id": 123, "first_name": "John"} ```` **v2:** Camel case ```json { "userId": 123, "firstName": "John" } ``` ### Pagination **v1:** Page-based ``` GET /api/v1/users?page=2&per_page=10 ``` **v2:** Cursor-based ``` GET /api/v2/users?cursor=abc123&limit=10 ``` ## Step-by-Step Migration ### Step 1: Update Authentication Replace query param auth with header-based: ```diff - axios.get('/api/v1/users?api_key=xxx') + axios.get('/api/v2/users', { + headers: { 'Authorization': 'Bearer xxx' } + }) ``` ### Step 2: Update Response Handling Adjust field name casing: ```diff - const userId = data.user_id + const userId = data.userId ``` ### Step 3: Update Pagination Switch to cursor-based: ```diff - const nextPage = page + 1 - fetch(`/api/v1/users?page=${nextPage}`) + const cursor = data.meta.next_cursor + fetch(`/api/v2/users?cursor=${cursor}`) ``` ## Testing Your Migration ```bash # 1. Test v2 in development curl -H "Authorization: Bearer xxx" https://dev-api.example.com/v2/users # 2. Run v1 and v2 side-by-side in staging # Compare responses for consistency # 3. Gradual rollout in production # Route 10% → 50% → 100% traffic to v2 ``` ## Support Resources - [API v2 Documentation](https://docs.example.com/v2) - [Migration Examples Repo](https://github.com/example/v2-examples) - [Support Channel](https://slack.example.com) ```` ## Backward Compatibility Strategies ### 1. Parallel Versions Run v1 and v2 simultaneously: ```typescript app.use('/api/v1', v1Router); app.use('/api/v2', v2Router); ```` ### 2. Adapter Pattern v1 calls v2 internally with adapter: ```typescript // v1 endpoint router.get("/api/v1/users", async (req, res) => { // Call v2 const v2Response = await v2Controller.getUsers(req); // Adapt v2 response to v1 format const v1Response = adaptV2ToV1(v2Response); res.json(v1Response); }); ``` ### 3. Feature Flags Gradual feature rollout: ```typescript if (req.version === "v2" && featureFlags.newPagination) { return cursorBasedPagination(req); } else { return pageBasedPagination(req); } ``` ## Client Communication Plan ### Announcement Email Template ``` Subject: [ACTION REQUIRED] API v1 Deprecation - Migrate by Dec 31 Hi API Consumers, We're deprecating API v1 on December 31, 2024. Please migrate to v2. What's changing: - Authentication: API keys → Bearer tokens - Response format: snake_case → camelCase - Pagination: page-based → cursor-based Migration resources: - Guide: https://docs.example.com/migration - Examples: https://github.com/example/v2-examples - Support: api-support@example.com Timeline: - Now: v2 available, v1 still works - Oct 31: v1 will show deprecation warnings - Dec 31: v1 will be shut down Questions? Reply to this email. ``` ## Monitoring Migration Progress ```typescript // Track version usage app.use((req, res, next) => { const version = req.path.includes('/v1') ? 'v1' : 'v2'; metrics.increment('api.requests', { version }); next(); }); // Dashboard metrics - v1 requests/day: 10,000 → 5,000 → 1,000 → 0 - v2 requests/day: 0 → 5,000 → 9,000 → 10,000 - Unique v1 consumers: 50 → 25 → 5 → 0 ``` ## Rollback Plan ```markdown ## If Migration Goes Wrong ### Symptoms - Spike in 5xx errors - Client complaints - Revenue impact ### Rollback Steps 1. Re-enable v1 endpoints 2. Update deprecation timeline 3. Communicate delay to clients 4. Fix issues in v2 5. Resume migration when stable ``` ## Best Practices 1. **Announce early**: 6+ months notice 2. **Provide tools**: SDKs, migration scripts 3. **Support clients**: 1-on-1 help if needed 4. **Monitor usage**: Track who's still on v1 5. **Gradual sunset**: Don't surprise users 6. **Clear docs**: Step-by-step guides 7. **Offer grace period**: Extensions for large clients ## Output Checklist - [ ] Versioning strategy chosen - [ ] Deprecation timeline (6+ months) - [ ] Migration guide written - [ ] Breaking changes documented - [ ] Backward compatibility plan - [ ] Client communication drafted - [ ] Monitoring dashboard setup - [ ] Rollback plan documented - [ ] Support resources prepared