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 | /api/v1/users | 明確、キャッシュ容易 | URLが長くなる |
| Header | Accept: application/vnd.api+json; version=1 | URLがシンプル | 発見しにくい |
| Query | /api/users?version=1 | シンプル | キャッシュ問題 |
| Content-Type | Content-Type: application/vnd.api.v1+json | 標準的 | 複雑 |
選択基準
| 条件 | 推奨方式 |
|---|
| RESTful純粋主義 | Header |
| 開発者体験重視 | URL Path |
| レガシー互換性 | Query |
| 新規プロジェクト | URL Path |
| 外部公開API | URL Path |
| 内部API | Header |
推奨: URL Path Versioning
/api/v1/users ← 現行バージョン
/api/v2/users ← 新バージョン
理由:
- 直感的で発見しやすい
- キャッシュが容易
- デバッグが簡単
- 広く採用されている
知識領域2: バージョン番号設計
Semantic Versioning（SemVer）原則
MAJOR.MINOR.PATCH
例: 1.2.3
| 種類 | 変更時 | URL反映 |
|---|
| MAJOR | 破壊的変更 | ✅ 反映（v1 → v2） |
| MINOR | 後方互換の機能追加 | ❌ 非反映 |
| PATCH | バグ修正 | ❌ 非反映 |
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）
| 変更種類 | 破壊的？ | 説明 |
|---|
| エンドポイント削除 | ✅ Yes | 既存クライアントが壊れる |
| フィールド削除 | ✅ Yes | 既存クライアントが壊れる |
| フィールド名変更 | ✅ Yes | 既存クライアントが壊れる |
| 必須フィールド追加 | ✅ Yes | 既存リクエストが無効に |
| 型変更 | ✅ Yes | パース失敗の可能性 |
| ステータスコード変更 | ✅ Yes | エラーハンドリング破損 |
| 認証方式変更 | ✅ Yes | 認証失敗 |
| オプションフィールド追加 | ❌ No | 後方互換 |
| 新エンドポイント追加 | ❌ No | 後方互換 |
| レスポンスフィールド追加 | ❌ No | 後方互換（通常） |
非破壊的変更
| 変更種類 | 注意点 |
|---|
| オプションフィールド追加 | デフォルト値を設定 |
| 新エンドポイント追加 | 既存に影響なし |
| レスポンスフィールド追加 | クライアントは無視すべき |
| 列挙値の追加 | クライアントは未知値を処理すべき |
知識領域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) を参照
判断基準チェックリスト
バージョン戦略
破壊的変更
非推奨化
移行サポート
関連スキル
.claude/skills/openapi-specification/SKILL.md: OpenAPI仕様書作成.claude/skills/request-response-examples/SKILL.md: バージョン別実例.claude/skills/authentication-docs/SKILL.md: 認証バージョニング
変更履歴
| バージョン | 日付 | 変更内容 |
|---|
| 1.0.0 | 2025-11-27 | 初版リリース |
