IBM Bluemix から SaaS で提供されている API Management サービスを使うと、普通に提供されている Web API に対して、その提供範囲を一部だけに限定(例えば GET/POST で提供されている API のうち、POST のものだけを公開)したり、認証機能を追加したり、(利用頻度や回数などの)アクセス制限をかけたり、API 利用状況をモニタリングする機能をラッピングする形で提供できるようになります。この辺りに関してはこちらのブログエントリにまとめているので参照ください:
IBM Bluemix の API Management サービス
この API Management サービスを使って既存の API をラッピングした場合、既存の Web API で指定していたURL パラメータやパスパラメータを、ラッピング後にどのように指定すればよいか?という疑問が生じます。その辺りについて調べてまとめてみました。結論としては「あまり意識せずに使える」ことになります。
例えば、既にこのような Web API が存在していたとします:{item_id} の部分に ID を指定して GET リクエストすることで、指定した ID のレコードを取得できる、というものです:
実際にウェブブラウザでリクエストした例がこちらです。この例では 1 という {item_id} を指定して目的のレコードを取得していますが、この 1 の部分を適宜変えることで目的のレコードを変更することができるような API になっている、という前提です:
このような Web API を API Management でラッピングする場合、この {item_id} というパスパラメータの存在をどのように指定すればよいか? というのが本ブログエントリの目的です。
結論はかなり簡単で、API を定義する際のパスにパラメータを {xxx} 形式で指定します。またその実装においてもプロキシー URL を指定する際に同じパラメータを使って指定します。
具体的には以下のような /get 関数を定義します。公開する API の形式を /get/{item_id} のように指定し、その実装のプロキシーURL において、 http://xx.xx.xx.xx/abc/items/{item_id} のようにそのまま指定するようにします。これで /get/ の後に1つパラメータを受け取って動くような挙動になっていることを指定したことになります:
また、URL パラメータはラッピング API を作成する際には特に宣言しなくても、そのまま使えます。例えば以下の URL を GET リクエストすると、レコードの一覧が取得できるような API が存在していて、limit=XX の部分で取得レコード数を指定できるような仕様になっていると仮定します:
この Web API を API Management でラッピングする場合は、URL パラメータのことは意識せずに、そのまま API を定義できます。下の例では公開 API に /list というパスを指定し、その実装のプロキシー URL は http://xx.xx.xx.xx/abc/items (URL パラメータ部分を省略したもの)までをそのまま指定します。これで /list 関数も定義できました:
このような指定方法で作成/公開したラッピングの API で、パスパラメータや URL パラメータを指定するには以下のようにします。まずは公開したラッピング API は Bluemix 内では「カスタム API 」として利用可能になっています(API Management で公開後に再ログインする必要があります)。まずはこのカスタム API を自分のランタイムにバインドしておきます:
バインドが成功すると、ランタイム内のサービスにカスタム API が追加できているはずです:
次にこの API を利用する際に必要な client_id と client_secret を確認します。メニューから「環境変数」を選び、このカスタム API を利用するための credentials 情報を確認します。そして url, client_id, client_secret の3つの値を確認してメモしておきます(この値はランタイムの環境変数 VCAP_SERVICES から参照できるので、アプリケーション内で動的に取得も可能です):
では実際に API Management を使って公開された API をパラメータを付けて利用してみましょう。まずレコードの ID をパス内で指定してレコードを取得する API の場合は、その ID をそのまま URL の最後に指定してブラウザでアクセスします。なお API Management 管理下の API にアクセスするには client_id と client_secret の値が必要なので、上記の環境変数から取得したそれぞれの値をそれぞれ指定して、以下のようなアドレスにウェブブラウザでアクセスします(以下は {item_id} に 1 を指定した例です):
すると、上記のラッピング前の Web API で実行した時と同じ結果を確認することができます。{item_id} の値を変更しても、正しい値が得られるはずです。これでパスパラメータについては API Management で管理できることがわかりました:
もう1つの、URL パラメータを指定する例も確認してみます。今度も client_id と client_secret と、更に limit の値も含めて URL パラメータに指定して、以下の様なアドレスにアクセスします(以下は limit に 10 を指定した例です):
この場合もラッピング前の Web API で実行した時と同じ結果が確認できるはずです(limit の値を変更すると、指定した数を上限とする結果セットが得られるはずです)。URL パラメータについては特に何もしなくても API Management に引き継いで管理できることが確認できました:
結論として、API Management でパラメータを使う場合は、以下の様な指定が必要です:
(1) URL パラメータの場合は、特に指定不要でそのまま
(2) パスパラメータの場合は、指定するパラメータを { } で括ったものを API 定義とプロキシー URL の両方に指定する
IBM Bluemix の API Management サービス
この API Management サービスを使って既存の API をラッピングした場合、既存の Web API で指定していたURL パラメータやパスパラメータを、ラッピング後にどのように指定すればよいか?という疑問が生じます。その辺りについて調べてまとめてみました。結論としては「あまり意識せずに使える」ことになります。
例えば、既にこのような Web API が存在していたとします:{item_id} の部分に ID を指定して GET リクエストすることで、指定した ID のレコードを取得できる、というものです:
http://xx.xx.xx.xx/abc/items/{item_id}
実際にウェブブラウザでリクエストした例がこちらです。この例では 1 という {item_id} を指定して目的のレコードを取得していますが、この 1 の部分を適宜変えることで目的のレコードを変更することができるような API になっている、という前提です:
このような Web API を API Management でラッピングする場合、この {item_id} というパスパラメータの存在をどのように指定すればよいか? というのが本ブログエントリの目的です。
結論はかなり簡単で、API を定義する際のパスにパラメータを {xxx} 形式で指定します。またその実装においてもプロキシー URL を指定する際に同じパラメータを使って指定します。
具体的には以下のような /get 関数を定義します。公開する API の形式を /get/{item_id} のように指定し、その実装のプロキシーURL において、 http://xx.xx.xx.xx/abc/items/{item_id} のようにそのまま指定するようにします。これで /get/ の後に1つパラメータを受け取って動くような挙動になっていることを指定したことになります:
また、URL パラメータはラッピング API を作成する際には特に宣言しなくても、そのまま使えます。例えば以下の URL を GET リクエストすると、レコードの一覧が取得できるような API が存在していて、limit=XX の部分で取得レコード数を指定できるような仕様になっていると仮定します:
http://xx.xx.xx.xx/abc/items?limit=100
この Web API を API Management でラッピングする場合は、URL パラメータのことは意識せずに、そのまま API を定義できます。下の例では公開 API に /list というパスを指定し、その実装のプロキシー URL は http://xx.xx.xx.xx/abc/items (URL パラメータ部分を省略したもの)までをそのまま指定します。これで /list 関数も定義できました:
このような指定方法で作成/公開したラッピングの API で、パスパラメータや URL パラメータを指定するには以下のようにします。まずは公開したラッピング API は Bluemix 内では「カスタム API 」として利用可能になっています(API Management で公開後に再ログインする必要があります)。まずはこのカスタム API を自分のランタイムにバインドしておきます:
バインドが成功すると、ランタイム内のサービスにカスタム API が追加できているはずです:
次にこの API を利用する際に必要な client_id と client_secret を確認します。メニューから「環境変数」を選び、このカスタム API を利用するための credentials 情報を確認します。そして url, client_id, client_secret の3つの値を確認してメモしておきます(この値はランタイムの環境変数 VCAP_SERVICES から参照できるので、アプリケーション内で動的に取得も可能です):
では実際に API Management を使って公開された API をパラメータを付けて利用してみましょう。まずレコードの ID をパス内で指定してレコードを取得する API の場合は、その ID をそのまま URL の最後に指定してブラウザでアクセスします。なお API Management 管理下の API にアクセスするには client_id と client_secret の値が必要なので、上記の環境変数から取得したそれぞれの値をそれぞれ指定して、以下のようなアドレスにウェブブラウザでアクセスします(以下は {item_id} に 1 を指定した例です):
(環境変数の url の値)/get/1?client_id=(環境変数 client_id の値)&client_secret=(環境変数 client_secret の値)
すると、上記のラッピング前の Web API で実行した時と同じ結果を確認することができます。{item_id} の値を変更しても、正しい値が得られるはずです。これでパスパラメータについては API Management で管理できることがわかりました:
もう1つの、URL パラメータを指定する例も確認してみます。今度も client_id と client_secret と、更に limit の値も含めて URL パラメータに指定して、以下の様なアドレスにアクセスします(以下は limit に 10 を指定した例です):
(環境変数の url の値)/list?client_id=(環境変数 client_id の値)&client_secret=(環境変数 client_secret の値)&limit=2
この場合もラッピング前の Web API で実行した時と同じ結果が確認できるはずです(limit の値を変更すると、指定した数を上限とする結果セットが得られるはずです)。URL パラメータについては特に何もしなくても API Management に引き継いで管理できることが確認できました:
結論として、API Management でパラメータを使う場合は、以下の様な指定が必要です:
(1) URL パラメータの場合は、特に指定不要でそのまま
(2) パスパラメータの場合は、指定するパラメータを { } で括ったものを API 定義とプロキシー URL の両方に指定する