More than 1 year has passed since last update.

IBM API Connect 関連メモ - (1)既存REST APIの取り込み

Last updated at 2022-10-19Posted at 2020-08-20

はじめに

API Connectはサービス呼び出しのためのAPIを管理するためのコンポーネントです。IBM Cloud上で提供されるものとオンプレ版がありますが、このシリーズではIBM Cloud上のAPI Connectを試してみた時の作業ログを記載していきます。
とりあえずAPI Connectのお勉強の手始めとしては製品が提供しているチュートリアルを中心にやっていきます。まず初回は既存のサービスのREST APIをAPI Connectに管理対象として取り込む操作をやってみます。

※基本的にはIBM Cloud上の無償枠の範囲で試しています。

参考情報

IBM Cloud資料- API Connect
Knowledge Center - IBM API Connect Version 5 documentation

事前調査

参考: API Connect のパッケージ化戦略および用語

レート制限は、あるプランのすべての操作で共有されるデフォルトのレートとして実装するか、API の特定の操作に対して設定できます。プランでは、API コンシューマーにさまざまなレベルのサービスを提供するために、異なるレート制限を使用できます。例えば、「デモ・プラン」は毎分 10 個の呼び出しのレート制限を適用し、「フルプラン」は毎秒 1000 個の呼び出しまで許可することができます。
製品は、一連の API とプランを、特定の使用を目的とした 1 つのオファリングにまとめてバンドルします。プランは製品内でのみ作成でき、その後、これらの製品はカタログ内で公開されます。製品とプラン間の関係には、以下のルールが適用されます。
- プランが属することのできる製品は 1 つのみです。
- 製品には、それぞれに異なる API のセットが含まれる複数のプランを組み込むことができます。
- ある製品内のプランは、別の製品内のプランと API を共有できます。
1 つの製品に複数のプランを組み込むことで、同じオファリングにそれぞれ異なるレベルのパフォーマンスを提供します。例えば、1 つの製品に、単一の API が使用可能な「デモ・プラン」と、複数の API が使用可能な「フルプラン」を組み込むことができます。

用語の整理

APIプロバイダー: サービスを提供してそれをREST APIとして公開する人・組織
APIコンシューマー: 公開されているREST APIを利用してアプリケーションを作成する人・組織
API: 管理対象のサービスを呼び出すための仕様。上の図のAPI1, API2はあるサービスに対する関連するオペレーション(操作)をまとめたものを指す(恐らくSwagger文書でまとめられる単位など)。
プラン: APIに対するアクセス制御や使用量を管理するための単位。
製品: 複数のAPIとそれに付随するプランをパッケージングしたもの。
カタログ: APIコンシューマーに対してAPIを提供する単位。製品をカタログに公開することでそのカタログに関連付いているコンシューマーに対してAPIが公開されることになる。製品を稼働させるランタイムのようなイメージ???。開発用/本番用など分ける目的で複数のカタログが使用される。カタログの設定で"開発モード"という設定があり、これを有効にしておくと競合する場合でもステージング、公開のアクションが強制的に実行される(デフォルトで提供されるカタログ"Sandbox"は開発モードが有効化されている)。
開発者ポータル: APIコンシューマー向けに提供される、公開されたAPIについてのポータルサイト。APIコンシューマーはこのサイトからAPI仕様などが確認可能。開発者ポータルはカタログに紐づく。
ステージング: 製品をカタログに登録する操作。ステージング後に公開処理を行うことで製品がコンシューマーに公開される。
アセンブル: API呼び出しが行われた時にAPI Connect上で実行される様々なロジックを組み込むことができ、その処理をアセンブルと呼んでいる。アセンブルの基本的な構成要素として、バックエンドのサービスを呼び出すinvoke,proxyなどがある。API Connectに管理対象のAPIを登録すると、API Connectをプロキシーとして実サービスを呼び出すことになるので、登録したAPIのバックエンド呼び出し部分をAPIプロキシーと呼んでいるようですが、このアセンブルがAPIプロキシーの実体と言えそうです。

API ConnectへのAPI登録までの大まかな流れ

(1) REST APIでアクセス可能なサービスの準備
API Connectとは別に、管理対象となるサービスがどこかで動いていて、REST APIでアクセスできることがまず大前提です。
(Loopbackプロジェクトはここでは扱いません)

(2) APIの定義
管理対象のサービスがどういうAPI仕様でアクセスできるのかを明確にしておく必要がありあす。
SwaggerというAPI記述の標準があるので、その標準に従ってSwagger文書(yamlベース)にてAPIの仕様を記述するのが王道かと思います。通常はSwagger文書はサービスプロバイダーが提供することになります(API Connectとは関係なく...)。

(3) 管理対象API仕様のAPI Connectへの取り込み
管理対象のAPIについてSwagger文書が提供されていれば、それをAPI Connectにインポートすることができます。
Swagger文書が提供されていなければ、API Connect上で定義を作ることができます。

(4) アセンブル(APIプロキシー)の作成
API Connectでバックエンド・サービスのAPIを管理するということは、API Connectがプロキシーのような位置づけで動作するということになります。つまり、APIを利用するフロントのアプリからするとエンドポイントはAPI Connectとなり、API Connect上では受け取ったリクエストに応じてバックエンドの実サービスを呼び出すといことをする必要があります。この時、単純にプロキシーのようにパススルーでバックエンドにリクエストを投げることもできますし、各種ロジックを持たせることもできます。例えば以下のような目的でアセンブルが利用されます。

複数のサービスを結合して1つのAPIとして公開したい
操作(パス)毎に処理内容を変えたい
メッセージ変換をしたい
API実⾏時に任意のフォーマットのログを出⼒したい
etc...

単純なパススルーでもアセンブルの作成は必要のようです。

(5) "製品"単位の集約、"プラン"の設定
管理対象のAPIをAPI Connect上に認識させたら、APIを公開するために"製品"という単位にまとめて、"プラン"を設定します。

(6) "カタログ"への登録、公開
"製品"を"カタログ"に登録(ステージング)し、公開処理をします。

(7) 開発者ポータル整備
カタログに紐づく"開発者ポータル"を作成し、APIコンシューマーの権限管理など整備します。

※当記事では(6)までの流れを確認しています。

チュートリアル実施

既存REST APIの取り込み (Swagger文書ありのケース)

参考: API 仕様のインポートと既存の REST サービスへのプロキシー作成 (IBM Cloud を使用する場合)

既にREST APIで呼び出せるサービスが存在し、そのAPIの定義がSwagger文書として提供されているケースを想定します。
Swagger文書をAPI Connectに取り込んでAPI Connectから接続テストを行うところまでをやってみます。

API Connectインスタンスのセットアップ

参考: API Connect インスタンスのセットアップ

IBM Cloudにログインして、カタログからAPI Connectを検索し、API Connectのパネルを選択します。

リージョンを選択し(東京は無かったので適当にシドニーを選択)、無料のLiteプランを指定。

下の方にスクロール。サービス名とかその辺は適当に設定して「作成」！

なんかできたっぽい。

デフォルトで"Sandbox"という名前の"カタログ"(開発モード)が作成されています。

既存のサービスの確認

API Connectのチュートリアル用(?)として一般に公開されているサービスがあるようです。このサービスにはREST APIでアクセスできるし、Webの画面も提されています。まずはそのアプリを動かしてみます。

以下のリンクを開きます。
Getting Started with API Connect

以下のようなWebの画面が開くので、LocationにUSのzip code(ここでは90210)を指定してGet Weatherボタンを押すと、そのzip codeの天気情報が表示されます。

このアプリにはREST APIでもアクセスできます。
ブラウザから以下のURLを指定してみます。
https://myweatherprovider.mybluemix.net/current?zipcode=90210

結果がJSONで返ってきました。

CURLで投げてもまぁ同じですね。

user01@DESKTOP-U7UON7M:/$ curl -X GET https://myweatherprovider.mybluemix.net/current?zipcode=90210
{"zip":10504,"temperature":57,"humidity":63,"city":"Armonk, North Castle","state":"New York","message":"Sample Randomly Generated"}

で、このサービスを呼び出すためのAPIの仕様は、Swagger文書として提供されています。
weather-provider-api_1.yaml

API仕様(Swagger文書)のインポート

API Connectインスタンスのダッシュボードの「>>」をクリック

ドラフトをクリック

APIタブから追加-ファイルまたはURLからAPIをインポートを選択

またはURLからインポート...をクリック

上のSwagger文書のURL(https://raw.githubusercontent.com/IBM-Bluemix-Docs/apiconnect/master/tutorials/weather-provider-api_1.yaml)を指定してインポート。

API仕様がAPI Connectに取り込まれました。

ここで使用しているSwagger文書を見てみると、x-ibm-... という項目をふくんでいます。これはどうやらAPI Connect特有の拡張のようで、一般的なAPI仕様というよりはAPI Connectに取り込む前提で作られたSwagger文書のようです。API仕様取り込み後は実際にはアセンブルを作成することになりますが、その部分の記述もSwagger文書に含まれている状態でサンプルとして提供されているようです。

取り込んだAPIを新規製品に追加、公開

アセンブルタブを開きます。
Swagger文書をインポートすると、バックエンドのサービスをパススルーで呼び出す単純なアセンブルが勝手に作成されています(元のSwagger文書に含まれて提供されている)。本来はここでアセンブルをカスタマイズすることになります。

右上のプルダウンメニューからデフォルト製品の生成をクリック

そのまま製品の作成！

右上に、「Sandboxにステージングしました」というメッセージが表示される。

API Manager テスト・ツールによるAPI呼び出しテスト

再生アイコンをクリックしてAPI呼び出しをテストします。

製品を選択して次へ。

操作のプルダウンからget/currentを選択して呼び出し。

応答が返ればOK

「探索」ツールによるAPI呼び出しテスト

右上の探索 - sandboxをクリック

Weather Provider APIから、GET/currentを選択し、右側のペインのTry itを選択、zipcodeに10504を指定してCall Operationをクリック。

結果確認

これでweatherというサービスのAPIをAPI Connectに登録して呼び出せることが確認できました。

既存REST APIの取り込み (Swagger文書なしのケース)

参考: API 仕様を追加して IBM Cloud で REST サービスを呼び出します。

既にREST APIで呼び出せるサービスが存在しているが、そのAPIの定義がSwagger文書として提供されていないケースを想定します。
この場合、API Connect上でAPIの定義を作成してあげる必要があります。
API Connectのインスタンスと、管理対象のサービスは上と同じものを使います。

新規API定義の作成

IBM Cloud上で、API Connectのダッシュボードから>>アイコンをクリック

ドラフトを選択

APIタブから追加-新規APIを選択

以下のように指定してAPIの作成をクリック

定義の右側の＋ボタンをクリック

名前にCurrent、タイプにObjectを指定します。

プロパティーのところで、以下のようなフィールドの定義を作成し、定義が出来たら右上の保存ボタンをクリックします。

同様にTodayの定義も以下のように作成して、完了したら保存します。

※ここで定義した2つのデータ構造は、weatherアプリのcurrent, todayのAPI呼び出しの応答データの構造を表しています。

左側のメニューからパスを選択し、＋ボタンをクリックします。

パスに/currentを指定、パラメーターに名前:zip, 場所:紹介, タイプ:string を指定、応答のスキーマにCurrentを指定し、保存します。

Todayについても同じようにパスを設定します。

アセンブルタブを開きます。

デフォルトで定義されているinvokeを削除します。

操作の切替をドラッグ&ドロップします。

追加した操作の切替をクリックし、右側のペインで、ケース0, ケース1にそれぞれget/current, get/todayを割り当てます。

呼び出しをドラッグしてget/currentの下にドロップします。追加したオブジェクトをクリックして、右側のペインで、タイトルに「invoke-current」、URLに「https://myweatherprovider.mybluemix.net/current?zipcode=$(request.parameters.zipcode)」を指定します。