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

## はじめに

IBM API Connect Enterrpise as a Service のドキュメントで、API ConnectのサンプルAPIチュートリアルが提供されています。
[Sample API and tutorial](https://www.ibm.com/docs/en/api-connect/saas?topic=overview-sample-api-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](https://youtu.be/xQXiiIXY0vU)

外部ネットワークにつながる環境であれば、オンプレや他のクラウドのAPI Connect v10の環境にもインポートして実行できます。

この記事では、このサンプルAPIチュートリアルについて、簡単にご紹介します。

なお、IBM API Connect as a Service on AWSの試用方法については、以下の記事を参照してください。
[IBM API Connect as a Service on AWS 試用版を使ってみる](https://qiita.com/myamane/items/39fe5940533fdbe76547 "IBM API Connect as a Service on AWS 試用版を使ってみる")

## サンプルAPIの概要
このAPI定義のアセンブリでは、二つのバックエンドシステム(AWS LambdaのREST API）を呼び出し、そのレスポンスをマージしてリクエスト先に戻しています。
API定義でのアセンブリの主な処理は
- ダミーの受注システムのAPIを呼んで、商品受注情報を取得
- ダミーの配送システムのAPIを呼んで、商品配送状況を取得
- これらのレスポンスをマージ
です。

チュートリアルの実施手順の詳細は、上記のGitHubやYouTubeで紹介されています。以下はチュートリアルの流れです。

[Step 1: サンプル定義を参照します。](https://github.com/ibm-apiconnect/sample-orders-api#step-1-click-here-to-access-the-sample-api-definition "Step 1. Click here to access the sample API definition")
[Step 2: API Managerで、サンプルのAPI定義をインポートし、アクティブにします。](https://github.com/ibm-apiconnect/sample-orders-api#step-2-import-the-sample-to-your-api-connect-instance "Step 2. Import the sample to your API Connect instance")
[Step 3: API Managerで、API定義を参照し、アセンブリでどのような処理がされているか、確認します。](https://github.com/ibm-apiconnect/sample-orders-api#step-3-explore-the-api-definition "Step 3. Explore the API definition")
[Step 4: API Managerのテスト画面でテスト呼び出しをし、応答が戻されることを確認します。](https://github.com/ibm-apiconnect/sample-orders-api#step-4-test-your-api "Step 4: Test your API")

ここまでが、基本的な動作確認の流れです。
チュートリアルでは、さらに、API定義のカスタマイズ（セキュリティパラメータとしてクライアントシークレットの追加）や分析画面の確認の手順が紹介されています。  
[Step 5: API定義にセキュリティパラメータ（クライアントシークレット）を追加します。](https://github.com/ibm-apiconnect/sample-orders-api#step-5-add-additional-security-requirements-to-your-order-tracking-api "Step 5: Add additional security requirements to your order tracking API.")
[Step 6: API Managerの分析画面でAPIの使用状況を確認します。](https://github.com/ibm-apiconnect/sample-orders-api#step-6-analyze-your-api-calls-and-responses-in-the-analytics-dashboard "Step 6: Analyze your API calls and responses in the analytics dashboard.")

## サンプルチュートリアルのアセンブリ処理の概要

API Connectでは、API定義にバックエンドのAPIを呼び出すためのInvokeポリシーを組み込んだり、データのマッピングを行うMapポリシーなどを組み込んで、API呼び出し時のカスタム処理を追加できます。
アセンブリや組み込みポリシーの詳細については、API Connectのドキュメント([API policies and logic constructs](https://www.ibm.com/docs/en/api-connect/saas?topic=definitions-api-policies-logic-constructs))を参照してください。
IBM API Connectでは、OpenAPI仕様を拡張して、カスタム処理を実装します。
[IBM extensions to the OpenAPI specification](https://www.ibm.com/docs/en/api-connect/saas?topic=file-extensions-openapi-specification)

サンプルAPIのアセンブリを確認します。
![assembly.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/193979/81fc5fca-2e22-f836-db92-6faee129d453.png)

このフローでは、5つの組み込みポリシーが使用されています。それぞれのポリシーでどのような処理が実施されているのでしょうか。

|タイトル      |組み込みポリシー|説明          |
|:---        |:---         |:--          |
|order lookup  |Invoke     |受注システム（ダミー）のAPIを呼び出し、受注情報を取得します。<br>ダミーの応答メッセージ例(JSON)：<br>{    <br>&emsp;"created_at": "2023-04-27T06:02:56.400678092Z",<br>&emsp;"shipped_at": "2023-04-30T06:02:56.40067907Z",<br>&emsp;"order_number": "256","status": "SHIPPED",<br>&emsp;"delivery_method": "UPS",<br>&emsp;"tracking_reference": "1Z001985YW90838348"<br>}|
|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の入力データとして利用されています。
![map1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/193979/16a51b95-825d-68ab-4290-2777232a6f10.png)

「combine data for response」のマッピングでは、order lookupの応答メッセージのorder部分と、lambda: track shipmentの応答メッセージ中のstatus項目部分を抽出、マージしたメッセージを生成し、応答メッセージとして戻しています。
![map2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/193979/9051b399-f88b-7928-5aca-d399f15706ab.png)

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