メインコンテンツまでスキップ

4.16. Allowing Versioning and Evolution (バージョニングと進化の許可)

4.16. Allowing Versioning and Evolution (バージョニングと進化の許可)​

アプリケーションプロトコルを設計する際の最も困難な側面の 1 つは, 既存のデプロイメントとの互換性を維持しながら, 時間の経過とともにプロトコルを進化させることができるようにすることです。

HTTP を使用するアプリケーションは, 最初から拡張性を考慮して設計すべきです (SHOULD)。これには以下が含まれます:

  • プロトコルネゴシエーション: クライアントとサーバーがどのバージョンまたは機能を使用するかをネゴシエートするメカニズムを提供する。

  • 優雅な劣化: 古いクライアントが新しいサーバーで動作できるようにする (その逆も同様), すべての機能をサポートしていない場合でも。

  • 機能検出: クライアントがサーバーがサポートする機能を検出できるようにする。

  • 未知の要素の無視: 実装が未知のヘッダーフィールド, コンテンツ, またはその他のプロトコル要素をエラーとして扱うのではなく, 無視すべきであることを指定する。

バージョニングへの一般的なアプローチには以下が含まれます:

  • メディアタイプのバージョニング: 異なるバージョンに異なるメディアタイプを使用する (例: application/vnd.example.v1+json, application/vnd.example.v2+json)。

  • URL のバージョニング: URL にバージョンを含める (例: /v1/resource, /v2/resource)。ただし, これはキャッシングとリソースの識別に問題を引き起こす可能性があります。

  • ヘッダーフィールドのバージョニング: カスタムヘッダーフィールドを使用してバージョンを示す。

  • 機能ベースのネゴシエーション: プロトコル全体のバージョニングではなく, 個々の機能のネゴシエーションを許可する。

アプリケーションは次のことを行うべきです (SHOULD):

  • バージョニングがどのように機能するかを明確に文書化する。

  • 下位互換性を維持する方法についてのガイダンスを提供する。

  • キャッシングやその他の HTTP 機能へのバージョニングの影響を考慮する。

  • 既存のバージョンに破壊的な変更を加えることを避ける; 代わりに, 互換性のない変更が必要な場合は新しいバージョンを定義する。

アプリケーションは次のことを行うべきではありません (SHOULD NOT):

  • バージョニングに URL クエリパラメータを使用する。これはキャッシングに干渉する可能性があります。

  • プロトコルの異なるバージョンが同じ識別子 (URL, メディアタイプ) を異なるものに使用する状況を作成する。

  • 新しいバージョンがリリースされたときにクライアントに即座にアップグレードを強制する。

に最終更新