.claude/skills/api-versioning/SKILL.md

API Versioning スキル

概要

APIバージョニング戦略の設計と後方互換性管理に関する専門知識を提供します。

コマンドリファレンス

# リソース参照
cat .claude/​skills/​api-versioning/​resources/​versioning-strategies.md
cat .claude/​skills/​api-versioning/​resources/​deprecation-process.md
cat .claude/​skills/​api-versioning/​resources/​breaking-changes.md

# テンプレート参照
cat .claude/​skills/​api-versioning/​templates/​migration-guide-template.md
cat .claude/​skills/​api-versioning/​templates/​deprecation-notice-template.md

---

知識領域1: バージョニング方式

主要な方式比較

選択基準

推奨: URL Path Versioning

/​api/​v1/​users     ← 現行バージョン
/​api/​v2/​users     ← 新バージョン

理由:

• 直感的で発見しやすい
• キャッシュが容易
• デバッグが簡単
• 広く採用されている

---

知識領域2: バージョン番号設計

Semantic Versioning（SemVer）原則

MAJOR.MINOR.PATCH
例: 1.2.3

URL表記

/​api/​v1/​...      ← メジャーバージョンのみ
/​api/​v1.2/​...    ← 避ける（複雑化）

バージョン選択ロジック

クライアントリクエスト → バージョン解決
├─ /​api/​v1/​users → API v1.x.x の最新を使用
├─ /​api/​v2/​users → API v2.x.x の最新を使用
└─ /​api/​users    → デフォルトバージョン（v1）を使用

---

知識領域3: 破壊的変更の定義

破壊的変更（Breaking Changes）

非破壊的変更

---

知識領域4: 非推奨化プロセス

段階的廃止フロー

1. 告知期間（2-4週間）
   ├─ ドキュメント更新
   ├─ Sunset ヘッダー追加
   └─ 移行ガイド公開

2. 警告期間（4-8週間）
   ├─ Deprecation ヘッダー追加
   ├─ ログ監視（使用状況）
   └─ 個別通知

3. 移行サポート期間（4-12週間）
   ├─ 新旧両方を並行稼働
   ├─ 移行サポート提供
   └─ 使用量モニタリング

4. 廃止実行
   ├─ エンドポイント無効化
   ├─ 410 Gone レスポンス
   └─ 代替エンドポイント案内

HTTPヘッダー

# 非推奨警告
Deprecation: true
Deprecation: @1735689600  # Unix timestamp

# 廃止日
Sunset: Sat, 01 Mar 2025 00:00:00 GMT

# 代替リソース
Link: </​api/​v2/​users>; rel="successor-version"

OpenAPI での非推奨マーク

paths:
  /​api/​v1/​users:
    get:
      deprecated: true
      summary: "[非推奨] ユーザー一覧取得"
      description: |
        ⚠️ このエンドポイントは2025年3月1日に廃止されます。
        代替: GET /​api/​v2/​users
      x-sunset-date: "2025-03-01"

---

知識領域5: 移行戦略

並行稼働パターン

期間1: v1のみ
期間2: v1（主）+ v2（ベータ）
期間3: v1（非推奨）+ v2（主）
期間4: v2のみ

バージョン分岐実装

// ルーティング例（Next.js）
// app/​api/​v1/​users/​route.ts
// app/​api/​v2/​users/​route.ts

// バージョン共通ロジック
// lib/​api/​users/​v1.ts
// lib/​api/​users/​v2.ts

データ変換レイヤー

// v1 → v2 変換
function transformV1ToV2(v1Data: V1User): V2User {
  return {
    id: v1Data.id,
    fullName: `${v1Data.firstName} ${v1Data.lastName}`, // フィールド統合
    email: v1Data.email,
    role: mapRoleV1ToV2(v1Data.role), // 値マッピング
    createdAt: v1Data.created_at, // 命名規則変更
  };
}

---

知識領域6: バージョン間差分文書化

変更ログ形式

# API Changelog

## v2.0.0 (2025-03-01)

### 破壊的変更

- `GET /​users` のレスポンス構造が変更されました
  - `first_name` + `last_name` → `full_name` に統合
- `role` フィールドの値が変更されました
  - `"admin"` → `"administrator"`

### 新機能

- `GET /​users/​{id}/​activity` エンドポイント追加
- ページネーションに `cursor` パラメータ追加

### 非推奨

- `GET /​users?page=N` は廃止予定（`cursor` を使用してください）

### 移行ガイド

詳細は [Migration Guide v1 → v2](./​migration-v1-v2.md) を参照

---

判断基準チェックリスト

バージョン戦略

• バージョニング方式が決定されているか？
• URLパターンが一貫しているか？
• デフォルトバージョンが定義されているか？

破壊的変更

• 変更は本当に破壊的か？
• 非破壊的な代替案はないか？
• 影響範囲を把握しているか？

非推奨化

• 十分な告知期間があるか？（最低4週間）
• 移行ガイドが準備されているか？
• Deprecation/​Sunsetヘッダーが設定されているか？
• 使用状況をモニタリングしているか？

移行サポート

• 新旧バージョンの並行稼働期間があるか？
• 移行ツールやスクリプトが提供されているか？
• サポート連絡先が明示されているか？

---

関連スキル

• .claude/​skills/​openapi-specification/​SKILL.md: OpenAPI仕様書作成
• .claude/​skills/​request-response-examples/​SKILL.md: バージョン別実例
• .claude/​skills/​authentication-docs/​SKILL.md: 認証バージョニング

---

変更履歴