api-versioning-deprecation-planner

API バージョニングと非推奨化の計画

既存のクライアントを壊さずに API を安全に進化させます。

バージョニング戦略

URL バージョニング（推奨）

/api/v1/users
/api/v2/users

メリット： 明確で、ルーティングしやすく、ドキュメントも簡単です デメリット： バージョンが増えると URL が煩雑になります

ヘッダーによるバージョニング

GET /api/users
Accept: application/vnd.api.v1+json

メリット： URL がすっきりします デメリット： テストが難しく、目立ちにくいです

クエリパラメーター

/api/users?version=1

メリット： 実装が簡単です デメリット： RESTful ではなく、指定を忘れやすいです

非推奨化のタイムライン

# 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

非推奨化を示すレスポンスヘッダー

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="alternate"
Warning: 299 - "This API version is deprecated. Migrate to v2 by Dec 31, 2024"

破壊的変更と非破壊的変更

非破壊的（安全）

✅ 新しいエンドポイントの追加 ✅ 任意のリクエストパラメーターの追加 ✅ レスポンスへのフィールドの追加 ✅ 新しいレスポンスステータスコードの追加 ✅ 必須フィールドの任意化

破壊的（新しいバージョンが必要）

❌ エンドポイントの削除 ❌ リクエストパラメーターの削除 ❌ レスポンスフィールドの削除 ❌ フィールド型の変更 ❌ 任意フィールドの必須化 ❌ 認証方式の変更

移行ガイドのテンプレート

# 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： キャメルケース

{ "userId": 123, "firstName": "John" }

ページネーション

v1： ページベース

GET /api/v1/users?page=2&per_page=10

v2： カーソルベース

GET /api/v2/users?cursor=abc123&limit=10

段階的な移行手順

ステップ 1：認証の更新

クエリパラメーターによる認証をヘッダーベースに置き換えます：

- axios.get('/api/v1/users?api_key=xxx')
+ axios.get('/api/v2/users', {
+   headers: { 'Authorization': 'Bearer xxx' }
+ })

ステップ 2：レスポンス処理の更新

フィールド名の大文字・小文字の形式を調整します：

- const userId = data.user_id
+ const userId = data.userId

ステップ 3：ページネーションの更新

カーソルベースに切り替えます：

- const nextPage = page + 1
- fetch(`/api/v1/users?page=${nextPage}`)
+ const cursor = data.meta.next_cursor
+ fetch(`/api/v2/users?cursor=${cursor}`)

移行のテスト

# 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

サポートリソース

• API v2 ドキュメント
• 移行例のリポジトリ
• サポートチャンネル

## Backward Compatibility Strategies

### 1. Parallel Versions
Run v1 and v2 simultaneously:
```typescript
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

2. アダプターパターン

v1 からアダプターを介して内部的に v2 を呼び出します：

// 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. フィーチャーフラグ

機能を段階的にロールアウトします：

if (req.version === "v2" && featureFlags.newPagination) {
  return cursorBasedPagination(req);
} else {
  return pageBasedPagination(req);
}

クライアントへの連絡計画

告知メールのテンプレート

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: [email protected]

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.

移行の進捗状況のモニタリング

// 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

ロールバック計画

## 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

ベストプラクティス

1. 早めに告知する： 6 か月以上前に通知します
2. ツールを提供する： SDK、移行スクリプト
3. クライアントをサポートする： 必要に応じて個別に支援します
4. 利用状況を監視する： まだ v1 を使っているユーザーを追跡します
5. 段階的に終了する： ユーザーを不意打ちにしないようにします
6. 明確なドキュメントを用意する： 段階的なガイドを提供します
7. 猶予期間を設ける： 大規模なクライアントには延長を認めます

成果物チェックリスト

• バージョニング戦略を選定済み
• 非推奨化のタイムライン（6 か月以上）
• 移行ガイドを作成済み
• 破壊的変更を文書化済み
• 後方互換性の計画
• クライアントへの連絡内容を作成済み
• モニタリングダッシュボードを設定済み
• ロールバック計画を文書化済み
• サポートリソースを準備済み