IBM API Connect as a Service on AWS のサンプルAPIチュートリアルの概要 #apiconnect

はじめに

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定義でどのような処理を実装するのかは、システム設計の重要な検討ポイントになります。