APIバージョニング戦略 - 後方互換性を保つ設計

APIバージョニングとは

APIバージョニングは、既存のクライアントを壊さずにAPIを進化させるための仕組みです。破壊的変更を導入する際に、新旧バージョンを共存させることで、クライアントが自分のペースで移行できるようにします。

なぜ必要か: APIを公開すると、多くのクライアントがそれに依存します。突然の変更はクライアントアプリケーションを壊し、信頼を損なう可能性があります。

破壊的変更とは

以下のような変更は、既存クライアントの動作を壊す可能性があります。

破壊的変更の例

非破壊的変更の例

• ✓ 新しいオプションフィールドの追加
• ✓ 新しいエンドポイントの追加
• ✓ 新しいオプションパラメータの追加

バージョニングの方式

1. URLパスバージョニング

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

メリット:

• 明確で直感的
• キャッシュが容易
• ブラウザからテストしやすい

デメリット:

• URIが変わるためRESTの原則に反するという意見も
• リソースのURIが固定されない

採用例: GitHub API, Twitter API, Stripe API

2. ヘッダーバージョニング

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

または

GET /api/users
X-API-Version: 1

メリット:

• URIがクリーン
• コンテンツネゴシエーションの標準に準拠

デメリット:

• ブラウザからテストしにくい
• ドキュメントがわかりにくい

採用例: GitHub API（一部）

3. クエリパラメータバージョニング

GET /api/users?version=1
GET /api/users?version=2

メリット:

• 実装が簡単
• デフォルトバージョンを設定しやすい

デメリット:

• パラメータを忘れやすい
• キャッシュの考慮が必要

採用例: Google APIs（一部）

比較表

バージョン戦略のベストプラクティス

1. 可能な限りバージョニングを避ける

// 拡張可能な設計
// 新しいフィールドを追加しても既存クライアントに影響なし
{
  "name": "Alice",
  "email": "alice@example.com",
  // 新しいフィールドを追加
  "profile": {
    "bio": "Developer"
  }
}

2. 非推奨化（Deprecation）プロセス

# レスポンスヘッダーで非推奨を通知
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

3. 移行期間の設定

4. 変更履歴の公開

## Changelog

### v2.0.0 (2024-06-01)
**Breaking Changes:**
- `user.name` を `user.firstName` と `user.lastName` に分割
- `GET /users/:id/posts` のレスポンス形式を変更

**Migration Guide:**
- `name` フィールドを使用している場合は、`firstName + ' ' + lastName` に変更してください

互換性を保つテクニック

フィールドの追加は安全

// v1
{ "id": 1, "name": "Alice" }

// v1.1 - 既存クライアントは新フィールドを無視
{ "id": 1, "name": "Alice", "email": "alice@example.com" }

Nullableフィールドとデフォルト値

// 新しいフィールドはnullableまたはデフォルト値を持つ
{
  "id": 1,
  "name": "Alice",
  "nickname": null,  // オプショナル
  "isActive": true   // デフォルト値
}

Envelopeパターン

// レスポンスをラップすることで拡張性を確保
{
  "data": { "id": 1, "name": "Alice" },
  "meta": { "version": "1.0", "requestId": "abc123" }
}

まとめ

APIバージョニングは、APIの進化とクライアントの安定性を両立させるための重要な戦略です。URLパスバージョニングが最も一般的で明確ですが、プロジェクトの要件に応じて適切な方式を選択してください。何より重要なのは、バージョニングの必要性を最小限に抑える拡張性の高い設計を心がけることです。