はじめに
IBM API Connect Enterrpise as a Service のドキュメントで、API ConnectのサンプルAPIチュートリアルが提供されています。
Sample API and tutorial
API定義(yamlファイル)はGitHubから入手可能で、API Connectへのインポート、テスト呼び出し手順が解説されています。
https://github.com/ibm-apiconnect/sample-orders-api
手順については、YouTube動画でも紹介されています。
Getting started with API Connect using the order tracking sample API
外部ネットワークにつながる環境であれば、オンプレや他のクラウドのAPI Connect v10の環境にもインポートして実行できます。
この記事では、このサンプルAPIチュートリアルについて、簡単にご紹介します。
なお、IBM API Connect as a Service on AWSの試用方法については、以下の記事を参照してください。
IBM API Connect as a Service on AWS 試用版を使ってみる
サンプルAPIの概要
このAPI定義のアセンブリでは、二つのバックエンドシステム(AWS LambdaのREST API）を呼び出し、そのレスポンスをマージしてリクエスト先に戻しています。
API定義でのアセンブリの主な処理は
- ダミーの受注システムのAPIを呼んで、商品受注情報を取得
- ダミーの配送システムのAPIを呼んで、商品配送状況を取得
- これらのレスポンスをマージ
です。
チュートリアルの実施手順の詳細は、上記のGitHubやYouTubeで紹介されています。以下はチュートリアルの流れです。
Step 1: サンプル定義を参照します。
Step 2: API Managerで、サンプルのAPI定義をインポートし、アクティブにします。
Step 3: API Managerで、API定義を参照し、アセンブリでどのような処理がされているか、確認します。
Step 4: API Managerのテスト画面でテスト呼び出しをし、応答が戻されることを確認します。
ここまでが、基本的な動作確認の流れです。
チュートリアルでは、さらに、API定義のカスタマイズ（セキュリティパラメータとしてクライアントシークレットの追加）や分析画面の確認の手順が紹介されています。
Step 5: API定義にセキュリティパラメータ（クライアントシークレット）を追加します。
Step 6: API Managerの分析画面でAPIの使用状況を確認します。
サンプルチュートリアルのアセンブリ処理の概要
API Connectでは、API定義にバックエンドのAPIを呼び出すためのInvokeポリシーを組み込んだり、データのマッピングを行うMapポリシーなどを組み込んで、API呼び出し時のカスタム処理を追加できます。
アセンブリや組み込みポリシーの詳細については、API Connectのドキュメント(API policies and logic constructs)を参照してください。
IBM API Connectでは、OpenAPI仕様を拡張して、カスタム処理を実装します。
IBM extensions to the OpenAPI specification
サンプルAPIのアセンブリを確認します。
このフローでは、5つの組み込みポリシーが使用されています。それぞれのポリシーでどのような処理が実施されているのでしょうか。
| タイトル | 組み込みポリシー | 説明 |
|---|---|---|
| order lookup | Invoke | 受注システム（ダミー）のAPIを呼び出し、受注情報を取得します。 ダミーの応答メッセージ例(JSON)： { "created_at": "2023-04-27T06:02:56.400678092Z", "shipped_at": "2023-04-30T06:02:56.40067907Z", "order_number": "256","status": "SHIPPED", "delivery_method": "UPS", "tracking_reference": "1Z001985YW90838348" } |
| parse response | Parse | Invokeポリシーの応答オブジェクトを解析し、後続フローのMapポリシーなどで、データ要素への参照を可能にします |
| map input to lambda | Map | Parseポリシーで解析されたオブジェクトデータ内の特定の項目を抽出、マッピングします |
| lambda: track shipment | Invoke | 配送システム（ダミー）のAPIを呼び出し、配送状況の情報を取得します |
| combine data for response | Map | 受注情報と配送状況の情報をマージして、応答メッセージを生成します |
実際のマッピングの画面を紹介します。
「map input to lambda」のマッピングでは、order lookupの呼び出しの応答メッセージ中の２項目(delivery_method, tracking_reference)がマッピングされており、この２項目は、実は後続のlambda: track shipmentの入力データとして利用されています。
「combine data for response」のマッピングでは、order lookupの応答メッセージのorder部分と、lambda: track shipmentの応答メッセージ中のstatus項目部分を抽出、マージしたメッセージを生成し、応答メッセージとして戻しています。
API定義をAPI ConectでこのAPI定義を実際に呼び出した時の応答メッセージ例は以下になります。
orderデータ部分のJSONのエレメントが一部順序が入れ替わっていますが、tracking_statusデータ部分とともに応答メッセージとして戻されてることがわかります。
{
"order_number": "128",
"tracking_status": [
{
"code": "SR",
"description": "Your package was released by the customs agency.",
"simplifiedTextDescription": "Delivered",
"statusCode": "003",
"type": "X"
}
],
"shipped_at": "2023-04-30T08:11:18.621052193Z",
"tracking_reference": "1Z001985YW90838348",
"status": "SHIPPED",
"created_at": "2023-04-27T08:11:18.62105138Z"
}
おわりに
今回は、サンプルチュートリアルで提供されている複数のバックエンドAPI呼び出しの概要をご紹介しました。
API Connectのシステム構築において、API定義でどのような処理を実装するのかは、システム設計の重要な検討ポイントになります。