6.3. URL によるバージョン管理

楽曲の検索用に異なるエンドポイントがある場合には (アーティストで検索、曲のタイトルで検索など)、URL によるバージョン管理では URI の一部に API バージョンを含めてください。以下に例を示します。

  1. api.songs.com/v1/songwriter
  2. api.songs.com/v2/songwriter
  3. api.songs.com/v1/song
  4. api.songs.com/v2/song
  5. 以下、同様
注記

この手法を用いる場合には、v1 の時点で API のバージョン管理を行うことを計画している必要があります。

この場合、3scale ゲートウェイは URI からエンドポイントおよびバージョンを抽出します。このアプローチでは、バージョンとエンドポイントの任意の組み合わせで、アプリケーションプランを設定することができます。続いて、メトリクスをこれらのプランおよびエンドポイントに関連付け、それぞれのエンドポイントおよびバージョンごとに、使用状況を把握することができます。

3scale 機能の柔軟性を以下のスクリーンショットに示します。

図6.1 バージョン管理計画機能

Versioning Plan Feature

後は、以下の図に示すように、3scale 管理ポータルの [your_API_name] > Integration > Configuration の順に移動し、URI をメトリクスにマッピングするだけです。

図6.2 メトリクスへの URI のマッピング

Mapping URIs to metrics

これで、異なる機能が有効になった 2 つの異なる API バージョンを使用することができます。それぞれの API の使用状況を、完全に管理し把握することができます。

API v2 に移行する必要があることをすべてのユーザーに伝える場合には、移行を依頼するメッセージを送信することができます。どのユーザーが移行したかを監視し、v1 の使用が減少して v2 の使用が増加する様子を確認することができます。3scale への承認呼び出しにメトリクスを追加して、v1 エンドポイントと v2 エンドポイントにアクセスする全トラフィック量を比較し、v1 を廃止しても問題ない時期を判断することができます。

図6.3 バージョン管理

Versioning

一部のユーザーが v1 を使用し続けている場合には、それらのユーザーを絞り込み、v2 への切り替えに関する新たなメッセージを送信することができます。

3scale では、3 段階のステップにより廃止の通知を送信することができます。

  1. Audience > Applications > Listing の順に移動し、廃止の通知を送信するアプリケーションプランを選択して Search をクリックし、リストを絞り込みます。
  2. チェックボックスをクリックし (複数選択可能)、問題の特定バージョンのユーザーをすべて選択します。新たなオプションが表示され、一括操作 (電子メールの送信、アプリケーションプランの変更、および ステータスの変更) を行うことができます。
  3. Send email をクリックし、手順に従って、非推奨バージョンをまだ使用しているお客様に廃止の通知を送信します。

以下の図を参照してください。

図6.4 廃止通知の送信

Sending deprecation note

エンドポイントに authrep 呼び出しが行われるたびに、認証は 1 度だけですが報告は 2 度行われます (エンドポイント用と API バージョン用にそれぞれ 1 度ずつ)。呼び出しは 1 度しか認証されないので、二重に請求することはありません。ある API バージョンの任意のエンドポイントに呼び出しを行うたびに、バージョン番号 (v1、v2 等) から名前を取ったメトリクスのヒット数が積算されます。これを使用して、バージョンごとの全トラフィックを相互に比較することができます。