10.3. URL によるバージョン管理
楽曲の検索用に異なるエンドポイントがある場合には (アーティストで検索、曲のタイトルで検索など)、URL によるバージョン管理では URI の一部に API バージョンを含めてください。以下に例を示します。
- api.songs.com/v1/songwriter
- api.songs.com/v2/songwriter
- api.songs.com/v1/song
- api.songs.com/v2/song
- 以下、同様
この手法を用いる場合には、v1 の時点で API のバージョン管理を行うことを計画している必要があります。
この場合、3scale ゲートウェイは URI からエンドポイントおよびバージョンを抽出します。このアプローチでは、バージョンとエンドポイントの任意の組み合わせで、アプリケーションプランを設定することができます。続いて、メトリクスをこれらのプランおよびエンドポイントに関連付け、それぞれのエンドポイントおよびバージョンごとに、使用状況を把握することができます。
3scale 機能の柔軟性を以下のスクリーンショットに示します。
図10.1 バージョン管理計画機能
後は、以下の図に示すように、3scale 管理ポータルの [your_API_name] > Integration > Configuration の順に移動し、URI をメトリクスにマッピングするだけです。
図10.2 メトリクスへの URI のマッピング
これで、異なる機能が有効になった 2 つの異なる API バージョンを使用することができます。それぞれの API の使用状況を、完全に管理し把握することができます。
API v2 に移行する必要があることをすべてのユーザーに伝える場合には、移行を依頼するメッセージを送信することができます。どのユーザーが移行したかを監視し、v1 の使用が減少して v2 の使用が増加する様子を確認することができます。3scale への承認呼び出しにメトリクスを追加して、v1 エンドポイントと v2 エンドポイントにアクセスする全トラフィック量を比較し、v1 を廃止しても問題ない時期を判断することができます。
図10.3 バージョン管理
一部のユーザーが v1 を使用し続けている場合には、それらのユーザーを絞り込み、v2 への切り替えに関する新たなメッセージを送信することができます。
3scale では、3 段階のステップにより廃止の通知を送信することができます。
- Audience > Applications > Listing の順に移動し、廃止の通知を送信するアプリケーションプランを選択して Search をクリックし、リストを絞り込みます。
- チェックボックスをクリックし (複数選択可能)、問題の特定バージョンのアプリケーションをすべて選択します。新たなオプションが表示され、一括操作 (電子メールの送信、アプリケーションプランの変更、および ステータスの変更) を行うことができます。
- Send email をクリックし、手順に従って選択したアプリケーションのオーナーに廃止の通知を送信します。
以下の図を参照してください。
図10.4 廃止通知の送信
エンドポイントに authrep 呼び出しが行われるたびに、認証は 1 度だけですが報告は 2 度行われます (エンドポイント用と API バージョン用にそれぞれ 1 度ずつ)。呼び出しは 1 度しか認証されないので、二重に請求することはありません。ある API バージョンの任意のエンドポイントに呼び出しを行うたびに、バージョン番号 (v1、v2 等) から名前を取ったメトリクスのヒット数が積算されます。これを使用して、バージョンごとの全トラフィックを相互に比較することができます。
