7
8

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

IBM API Connectで既存のAPIを公開してみる

Last updated at Posted at 2016-11-22

はじめに

API Connectを使って、既存のREST APIを公開する方法を紹介します。
API ConnectのBluemix版でもオンプレ版でも同じ操作でできるはずですが、バージョンの違い等により操作や手順が異なってしまう可能性はありますのでご了承ください。

IBM API Connectとは

API Connectは、既存のエンタープライズIT資産をAPIとして公開するためのAPIプロバイダー向けの包括的な基盤ソリューションです。最近は以下のような図が使われていますが、API自体を作成して実行する機能も提供し、そのAPIを公開するために管理と保護の機能まで包括的に提供しているのがAPI Connectの特長です。
API Connect全般の説明や、作成・実行の機能については、IBM API Connect 使ってみた〜APIを作る〜でも説明されています。

apic_logo.png

当記事では、既存のAPIを、管理・保護の機能を利用して公開する方法を中心に説明します。

既存のAPIの説明

APIの公開の手順としては、API Connectのマニュアルのチュートリアルをベースにします。
利用する既存のAPIとしては以下のURLにGET操作でアクセスできるサンプルAPIを利用します。これはある銀行の支店情報の一覧を返すAPIです。
https://apim-services.mybluemix.net/banka/v1/branches
ブラウザなどからアクセスすると、支店情報の一覧がレスポンスとして取得できます。(以下は、レスポンスの一部の表示例です。)

existing_branch_api_response.png

このAPIをAPI Connectの機能を利用して公開していきます。

既存のAPIの公開方法

以下のステップで既存の支店情報取得APIを公開します。

  1. 公開API定義の作成
  2. 公開APIのテスト
  3. 公開API用の製品およびプランの作成
  4. 製品の公開

1. 公開API定義の作成

まず、API Managerから公開APIの定義を作成します。
APIマネージャーのUIにログインします。APIマネージャーは、以下のURLからアクセスできます。
https://<Managementサーバーのアドレス>/apim

Bluemixの場合は、IBM Bluemix で無料の IBM API Connect インスタンスを作るを参考にしてください。

APIマネージャーのUIにログインすると、左上にナビゲートアイコン apimanager_navigate_icon.png が表示されています。まずはここをクリックして、基本バナーを表示して実施する操作に応じたメニューに入ります。
APIの定義をするには、ドラフトメニューに入ります。
apimanager_banner_1.png

ドラフトメニューに入ると、上部に製品APIのタブが表示されています。まずはここからAPIのタブをクリックして、追加アイコン apimanager_add_icon.png をクリックして、公開するAPI定義を追加します。
追加アイコンをクリックすると、API定義を追加する方法がいくつか用意されていることが分かります。外部で作成したOpenAPI記述(Swagger 2.0記述)をインポートすることもできます。今回は、スクラッチで定義するため、一番上のAPIを選択します。
apimanager_api_add_menu_1.png

以下の例を参考にAPI定義の基本情報を入力して、Create APIボタンをクリックします。
apimanager_add_api_1.png

API定義が作成され、APIの設計タブが開きます。
API定義に必要な設定をここで追加することができます。
左のメニューの中からセキュリティー定義セクションに移動してみると、クライアントID(APIキー)の定義がデフォルトで設定されていることが分かります。
api_security_def_apikey.png

セキュリティーセクションに移動すると、セキュリティー定義セクションで定義されたクライアントIDcliendIdHeader(APIキー)にチェックが入っており有効になっていることが分かります。
この設定が行われていることで、アプリケーションごとに発行するクライアントID(APIキー)を付けてAPI呼び出しを行うことを強制し、アプリケーションごとにAPIへのアクセス制御を行うことができます。
api_security_apikey.png

パスセクションに移動して、どのパスでどの操作のリクエストを受け付けるのかを定義していきます。パスセクションで追加アイコン add_icon.png をクリックすると、---1という名前で新規パスが追加されるので、パスの名前をdetailsに編集します。
api_path_edit.png

API作成時に設定した基本パス/branchesの後ろに、ここで設定したパスを付けて、/branches/detailsというパスでAPI操作を受け付けることになります。このパスにデフォルトでGET操作が定義されています。今回公開するAPIもGET操作として公開するので、この設定を編集していきます。

ここで、各操作のパラメーターや要求・応答メッセージのフォーマットを定義します。ここで定義しておけば、Open API(Swagger 2.0)記述に反映され、APIを公開した際に、APIを利用するアプリ開発者が開発者ポータルからAPI仕様の詳細を確認したり、Open API(Swagger 2.0)記述のダウンロードもできるようになります。

今回のGET操作ではパラメーターはないため、応答メッセージのフォーマットのみを設定します。
定義セクションに移動し、追加アイコンadd_icon.pngをクリックして、以下のようにaddressという名前に変更します。
api_def_add.png

プロパティーの追加をクリックして、この定義に以下のように5つのプロパティーを設定します。
def_property.png

もうひとつ定義セクションで定義を追加して、branchという名前にします。
api_def_add2.png

プロパティーの追加をクリックして、この定義に以下のように3つのプロパティーを設定します。ここで、プロパティーaddressのタイプに、先ほど定義したaddressを設定します。このように、API内の他の定義を参照して階層化しているデータ構造も定義することができます。
def_property2.png

これでdetailパスの応答メッセージのフォーマットの定義ができたので、パスセクションのdetailsパス定義に戻り、GET操作を展開します。
api_path_edit2.png
応答のセクションで、状況コードが200の応答メッセージのスキーマとして、先ほど設定したbranch定義をドロップダウンより選択します。
api_path_edit_response_1.png

ここまで設定したら、右上の保存アイコンsave_icon.pngをクリックして設定を保存します。

さて、ここまででAPIの仕様を定義してきましたが、先ほども少し説明したように、ここで定義した内容は開発者ポータルに表示される内容となりますので、できるだけ親切に分かりやすくしてあげる必要がありますよね。
たとえば応答メッセージのフォーマットを定義しましたが、「説明」や「例」にはできるだけ分かりやすいものを記入しておいてあげると利用者に親切なAPIになるかと思います。APIのデザインにおいては、APIそのものを使いやすく設計することももちろん重要と思いますが、使う方に分かりやすく情報提供することもそれと同じくらい重要なポイントになると思います。

次にアセンブルタブに移動して、既存のAPIを呼び出す設定を行います。
api_sssemble_tab_1.png

ここで、APIゲートウェイでAPIのリクエストを受け付けたあとの処理を実装していきます。
左側に利用できるポリシーが並んでいますが、左上のポリシーのフィルターアイコンapi_sssemble_filter.pngをクリックすると、Micro GatewayポリシーDataPower Gatewayポリシーが選択できるようになっています。選択を変えると、その下に表示されるポリシーの種類が変わることが確認できます。Gatewayの種類によって利用できるポリシーが異なるからです。ここで、使っているゲートウェイに応じて正しく選択をしておくことを忘れないようにしましょう。Bluemixを利用している場合や、オンプレでDataPowerを利用している場合は、DataPower Gatewayポリシーにチェックを入れます。
api_sssemble_gw.png

デフォルトでinvokeポリシーが配置されていますが、最低限バックエンドのAPIを呼び出す設定をしなければなりません。invokeポリシーをクリックすると、右側にプロパティー・シートが表示されるので、バックエンドのAPIのURLを、プロパティーのURLに入力します。

ここまででAPIの設定が完了しましたので、右上の保存アイコンsave_icon.pngをクリックして設定を保存します。

さて、ここで、ソースタブをクリックしてみてみると、これまで設定した内容がOpen API(Swagger 2.0)記述として確認できるようになっています。
設計タブで設定した内容のほか、アセンブルタブで設定した内容もIBM拡張として、x-ibm-configuration オブジェクトを使用して、定義されていることがわかります。つまりAPIマネージャーで定義したAPIの定義内容はすべてここに含まれているので、この定義をエクスポートして別の環境でインポートすれば定義をそのままコピーできますし、バックアップとしても便利ですね。
api_source_tab.png

2. 公開APIのテスト

ここまでの手順で定義したAPIが正しく動作するか、APIマネージャーのテスト機能を利用してテストしてみましょう。

アセンブルタブの左上のテストアイコンapi_sssemble_test_icon.pngをクリックすると、テストメニューが表示されます。セットアップの変更をクリックして、公開するためのカタログや製品の設定をします。
api_sssemble_test_change_setup.png

カタログや製品については後の章で説明しますので、ここでは、とりあえず、カタログにはSandboxを選択します。
api_sssemble_test_catalog.png

下にスクロールして新しい製品の名前として、banking-servicesと入力して作成および公開をクリックして、次へをクリックします。
api_sssemble_test_product.png

呼び出す操作を選択する画面が表示されるので、プルダウンからget /detailsを選択します。
api_sssemble_test_method.png

下にスクロールして呼び出しをクリックすると、APIのテスト呼び出しが実行されます。
api_sssemble_test_run.png

呼び出しが成功すると、以下のように表示され、ヘッダーの内容やレスポンス本文が表示されます。
api_sssemble_test_result.png

問題がある場合や修正したい場合には、APIの設定を変更して、再度保存し、テストのメニューから製品の再公開を行った上で呼び出しを実行します。再度公開しないと、変更内容が反映されません。
以上でテストは終了です。

3. 公開API用の製品およびプランの作成

APIの定義が終わりテストが完了したので、ここから公開に向けて、製品プランの設定を行います。
製品というのは、APIをステージングしたり公開する際の単位で、1つ以上のAPIを製品に含めて、公開を行います。
製品の中には1つ以上のプランを設定します。プランは、APIを利用するアプリケーションのAPIへのアクセス可否と利用回数(レート制限)を制御する単位となっています。
今回は、1つのAPIを製品に含めて、レート制限の異なるプランを2つ作成してみましょう。

  • ベーシックプラン : レート制限 10回/分
  • ライトプラン : レート制限 5回/分

実は、先ほどの手順でテストを行った際に、製品プランは作成されてしまっています。プラン製品を作成したタイミングでデフォルトで1つが自動的に作成されています。先ほどの手順で作成した製品を修正する形で設定をしていきましょう。すべてのAPIをクリックしてAPIの一覧に戻ります。
api_all_api_1.png

製品タブをクリックして、テストを行った際に作成したbanking-services製品をクリックして設定画面を表示します。

api_product_api.png

左側のメニューからAPIセクションを見ると、支店情報取得APIが表示されており、この製品に含まれているAPIが分かります。さらにここから、製品に含めるAPIを追加することもできます。
product_api.png

プランセクションを確認しましょう。デフォルトでデフォルトのプランという名前のプランが定義されていますね。デフォルトのプランを展開して設定を変更していきます。
product_default_plan_edit.png
以下のように設定します。
product_basic_plan.png

もうひとつプランの設定を追加します。プランセクションでプランの追加アイコンadd_icon.pngをクリックすると新規プラン1という名前でプランが作成されるので、展開をして以下のように設定をします。
product_light_plan.png

以下のように2つのプランを設定できました。
product_plan_setting.png

ここで、製品に設定する内容として、プラン以外に重要な情報があります。設計タブの問い合わせ先セクションで、製品に関する問い合わせ先やライセンス情報、利用条件などを登録できます。ここで登録しておくことで、開発者ポータルに表示されます。以下の例を参考に、登録してみてください。
product_info.png

ここでソースタブをクリックしてみると、APIと同様に、製品に対する設定内容がyaml形式で分かるようになっています。こちらもAPIと同様に、ダウンロードして別の環境にコピーしたり、バックアップとして利用することができます。

右上の保存アイコンsave_icon.pngをクリックして設定を保存します。

これで製品とプランの設定が完了しました。

4. 製品の公開

設定した製品を公開していきます。
製品を公開するには、まずステージングを行います。ステージングをすると、APIゲートウェイ上にデプロイされます。

製品の編集画面の右上のステージングアイコンproduct_staging.pngをクリックすると、ステージング可能なカタログが表示されるので、Sandboxをクリックしてステージングします。
product_staging_sandbox.png

カタログとは、ゲートウェイのランタイム環境のことで、テスト環境や開発環境など、目的別に作成することができます。カタログを複数作っておくことで、目的別に論理的に独立した環境を利用して開発やテストを行うことができます。デフォルトではSandboxのみが用意されています。

ステージングが完了すると、カタログの管理メニューから公開の操作を行います。
カタログの管理メニューに入るには、左上のナビゲートアイコン apimanager_navigate_icon.png から、ダッシュボードをクリックします。
apimanager_banner2_1.png

ここでカタログの一覧が表示されますが、デフォルトではSandboxだけですね。製品をステージングしたSandboxをクリックします。
sandbox.png

ステージングした製品banking-servicesステージング済みステータスでこのカタログにステージングされていることが分かりますね。banking-services製品をクリックすると、この製品に含まれるAPIやプランが確認できて分かりやすいですね。
banking_service.png

ここでステージング状態の製品を公開しましょう。
製品名の右の管理アイコンadmin_icon.pngをクリックして、公開を選択します。
product_publish.png

以下のように可視性およびサブスクライバーの編集画面が表示されます。これは、開発者ポータルに公開した際に、アプリ開発者に対する表示可否とサブスクライブ可否を設定するものです。この設定により、開発者ポータルにログインしたアプリ開発者ごとに見せる製品を変えたり、利用可能な製品を制御することができるようになっています。
ここではそのまま、公開ボタンをクリックして公開します。
product_publish2.png

公開されると、製品のステータスが以下のように公開済みとなります。
product_published.png

以上で製品の公開が完了し、外部からAPIが利用できる状態となりました。

次の回では、開発者ポータルからの利用と、外部からのAPI呼び出しについて書きたいと思います。

7
8
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
7
8

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?