MuleSoftにおけるRAMLを使ったAPIの実装

2024-12-20

MuleSoftにおけるRAMLを使ったAPIの実装

記事をシェアする

※この記事は、主にMuleSoftが気になっている方およびこれからMuleSoftに挑戦する方を対象としています。そのため、一部の用語に関しては説明を割愛しています。

執筆のきっかけ
MuleSoftとは
MuleSoftのAPI開発で使用する主なツール
- 【Anypoint Studio】
- 【Advanced REST Client】
今回作るAPIの概要
Design CenterでAPIを作成してみた
- APIの作成
- APIのエンドポイント作成
- リクエストパラメータの定義
- レスポンスパラメータの定義
Mockを使った簡単なテスト
- API仕様定義の確認
- テストツールを用いたMockテスト
作成したAPIをExchangeにPublishする
Anypoint StudioでAPIを実装してみた
- Anypoint Studioに作成したAPIをImportする
- エンドポイントのフロー自動生成
- 処理フローの実装
実際に動かしてみた
- ローカル環境へのデプロイ
- エラー時の挙動確認
- 実行環境(CloudHub)へのデプロイ
まとめ
参考リンク集

執筆のきっかけ

MuleSoftによるAPI開発では、APIの実装前にRAML(RESTful API Modeling Language)を使ってAPI仕様定義を行います。しかし、RAMLの知識がない方が触れるには、MuleSoftが提供する情報やテンプレートが少ないため、記述ルールや製品仕様の理解が難しいです。
この記事ではRAMLの記述方法を中心に、APIの実装、ローカル環境と実行環境へのデプロイ手順をまとめていますので、こちらを参考にMuleSoftに触れてほしいです。

MuleSoftとは

MuleSoftとは、Salesforceが提供するローコード開発に対応したiPaaS製品です。MuleSoftでは、Anypoint PlatformとAnypoint Studioの2つのサービスを活用します。
Anypoint Platformは、マネジメントコンソールとして機能し、RAMLを使ったAPIの仕様定義や作成したAPIの管理、実装したAPIを実行環境へデプロイすることができます。
Anypoint StudioはEclipseベースのIDE（Integrated Development Environment）で、GUI(Graphical User Interface)でAPIの実装と実行環境およびローカル環境へのデプロイができます。
MuleSoftにおけるAPI開発には、以下のステップがあります。

API仕様をRAMLで作成
MockでAPI仕様の動作確認
APIをExchangeに公開
RAMLから実装スケルトンを自動生成
APIをローコードで実装＆デプロイ
APIの動作確認

今回はこの流れを紹介します。

MuleSoftのAPI開発で使用する主なツール

【Anypoint Studio】

APIの実装に使います。ローカル環境へのデプロイやデバッグによる動作確認ができます。

https://www.mulesoft.com/jp/platform/studio ⧉

【Advanced REST Client】

Google Chromeの拡張機能であり、APIのテストツールです。クライアント側からリクエストを送信し、レスポンスを確認できます。

https://install.advancedrestclient.com/ ⧉

今回作るAPIの概要

お試しとして、レストランの予約情報を取得および更新するAPIを作成します。API仕様定義はAnypoint PlatformのDesign Centerで行います。
流れとしては、Design Centerで作成したAPIをExchangeにPublish後、Anypoint Studioに取り込み、実装を行い、ローカル環境および実行環境にデプロイします。リクエストを送信し、レスポンスや異常時の処理を確認します。

Design CenterでAPIを作成してみた

Design CenterではAPI仕様定義だけでなく、作成したエンドポイントへのリクエストに対し、期待通りのレスポンスが返されるかをMocking Serviceを利用して確認することができます。まずはAPIの作成を行います。

APIの作成

作成したトライアルアカウントでAnypoint Platformにログインします。ログイン後、画面左上のメニューボタンからDesign Centerに移動してAPIを作成します。APIを作成するには以下の手順を実施します。

alt text

Design Centerで画面左上のCreateを押す。
New API Specificationを選択する。
※リクエスト、レスポンスで使うデータのメタデータおよび値は、New Fragmentを選択することでフラグメントとして別プロジェクトに切り出して、複数RAMLから参照・再利用することができます。
プロジェクトの名前を入力したらCreate API を押す。

alt text

APIのエンドポイント作成

次にエンドポイントを作成します。
※RAMLではエンドポイントに限らず全ての要素の末尾に:をつける必要があります。
※API仕様を構成する要素ごとに階層が定められており、階層をインデントで表現するため、インデントの個数は厳密にチェックされます。

/エンドポイント名:と記述し、エンドポイントを作成する。
※エンドポイントのみ先頭に/をつけます。
※パスの前方が一致するエンドポイントが複数ある場合、一致するパスに紐づけて階層化できます。

1
/reserve/restaurant
2
/reserve/hotel
3
↓
4
/reserve:
5
  /restaurant:
6
  /hotel:

URIパラメータに関しては、/{パラメータ名}:と記述する。
メソッドを記述する。　※複数設定可。例）同じパスで参照はGET、更新はPOSTなど。

alt text

リクエストパラメータの定義

リクエストパラメータは要件に応じて適宜定義します。以下の手順は一例です。

ヘッダーがある場合、headers:を記述する。
ヘッダー項目を定義する。
必須項目はrequired: true。必須でない項目はrequired: falseを記述する。
※記載がない場合、デフォルトで必須となる。
形式に関しては、type:で定義する。
文字列長や最大値、正規表現も定義できる。　例）maxLength: 5, maximum: 10, pattern: \d*
※正規表現はJavaScriptに準ずる。
リクエストボディがある場合、body:を記述する。
リクエストボディの形式を指定する。　例）application/json
リクエストボディに関しては、properties:を記述し、その下行にボディ項目を定義する（定義の仕方は手順2~5同様）。
※properties:の他にもexample:を記述することで、ボディ例および項目ごとの例を設定できる。

alt text

レスポンスパラメータの定義

レスポンスパラメータの定義方法は以下です。

responses:を記述する。
ステータスコードを選択する。　例）200
body:を記述する。
コンテントタイプを選択する。　例）application/json
リクエストパラメータ定義の手順8同様、レスポンスボディを定義する。

alt text

【RAMLの言語仕様についてはこちら】

RAMLの詳細をより知りたい方は、こちらが参考になります。

https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md ⧉

Mockを使った簡単なテスト

右のタブ(Documentation)からテストしたいエンドポイントまたはメソッドを選択する。
Try itを選択する。
Try it押下後、Mockテストを実施できるようになる。テスト用のリクエストURLが生成され、API仕様に応じてURIパラメータ、クエリパラメータ、ヘッダーを入力する。
Sendを押す。

alt text

API仕様定義の確認

API仕様定義が正しく機能しているか確認するために、以下パターンとその結果を表示します。

ヘッダーのcustomerIdが無効
- 必須項目のため、customerIdがない旨のエラーとなる。
ヘッダーのcustomerIdが4桁
- GETメソッドのcustomerIdのため、4桁では文字列長エラーとなる。
ヘッダーのcustomerIdが4桁
- POSTメソッドのcustomerIdのため、4桁でも正常となる。
ヘッダーのcustomerIdが全角数字
- 入力値が有効でない旨が入力画面に表示されている（エラーがなかなか返されない）。

テストツールを用いたMockテスト

※歯車と鉛筆のアイコン(Mocking Service Configuration)をクリックし、パブリック用リンクを生成することで、Advanced REST ClientやPostmanなどの外部APIテストツールからMockテストすることもできます。

alt text

作成したAPIをExchangeにPublishする

APIの作成が完了したらExchangeにPublishしますが、特に画面遷移を行う必要はないです。

Design Centerの右上にあるPublishを押下する。
Asset versionとAPI versionが自動で入力されているのでPublish to Exchangeを押下する。
Publishing to Exchange画面が出ればPublish成功。
Publishing to Exchange画面のExchangeを押下し、Exchangeに移動する。
作成したAPIがあることを確認する。

alt text

Anypoint StudioでAPIを実装してみた

Anypoint Studioに作成したAPIをImportする

ExchangeにPublish後、Anypoint StudioでMuleプロジェクトを作成し、ExchangeにPublishしたAPIを取り込みます。

Anypoint Studioを開き、左のPackage ExplorerからCreate a Mule Projectを選択する。
Project Nameを入力しFinishを押下する。
※Design Centerで作成したAPIと同じ名前にすると、実行環境へのデプロイで失敗するので注意してください。
※大文字で入力しても、小文字に変換して作成されます。
Package Explorerにある作成したプロジェクトで右クリックし、Manage Dependencies→Manage APIsを選択する。
図の緑の「+」(Add new dependency)を押下し、from Exchangeを選択する。
図の検索バーに作成したAPI名を入力するとAvailable compatible modulesにExchangeに存在するヒットしたAPIが表示される。
作成したAPIを選択しAddを押下するとSelected modulesに反映される。その後、Finishを押す。
APIが追加されていることを確認し、Apply and Closeを押下する。
Do you want to scaffold API名 specification?と聞かれるのでYesを選択する。
作成した数の分だけエンドポイントのフローが自動生成される。

alt text

エンドポイントのフロー自動生成

alt text

処理フローの実装

APIの実装は、Anypoint Studioの右側のMule Paletteから、各コネクタのコンポーネントをドラッグ＆ドロップしてフロー内に追加します。
よく使うコンポーネントとして、payloadを設定するSet Payloadや入力データを整形するTransform Message、変数に格納するSet Variableやログを出力するLoggerがあります。
※Anypoint Studioでは、入力データおよび出力データはpayloadに格納されます。
コンポーネントのディスプレイ名を変更することで、各コンポーネントがどのような処理を行うか把握しやすくなります。

alt text

実際に動かしてみた

ローカル環境へのデプロイ

ローカル環境にデプロイして、Advanced REST Clientでリクエストを送り、挙動を確認(デバッグ)します。

プロジェクトか処理フロー実装画面の空いているスペースで右クリック、またはRunタブをクリックし、Debug project プロジェクト名を選択する。
※通常起動する場合はRun project プロジェクト名。
Console画面にDEPLOYEDと表示されていることを確認する。
※リクエストを送る際に使うURLは、Console内でCtrl+Fを押して検索機能を呼び、localhostと検索します（http://localhost:8081(ポート番号)/console/となっているので、http://localhost:8081(ポート番号)/api/に修正して使用します）。
Advanced REST Clientを開き、URLおよびヘッダー等に必要な入力をしてリクエストを送る。
正常レスポンスが返却される。

alt text

エラー時の挙動確認

エラー時の挙動を確認するためにヘッダーのcustomerIdなしでリクエストを送信し、エラーを発生させます。

APIkit RouterでAPI:BAD_REQUESTエラーが発生する。
API:BAD_REQUESTをハンドリングするエラーハンドラーでキャッチされる。
エラーハンドラーのフロー内でレスポンスが整形される（レスポンスは、{message: "Bad request"}が返されます）。
Advanced REST Clientに成形されたレスポンスが返却される。

alt text

きちんとエラーハンドラーで処理され、期待通りのレスポンスが返ってきています。

実行環境(CloudHub)へのデプロイ

最後に、MuleSoftのCloudHubにデプロイする方法を紹介します。

プロジェクトで右クリックをして、Anypoint Platform→Deploy to CloudHubを選択する。
環境を選択する（今回はSANDBOXを選択します）。
Deploying Application画面が表示され、Deploy Applicationを押す。
※デプロイする際の設定はこちらで行います（今回は特に設定していません）。
Application makesample successfully deployed to CloudHub-XX-XXXX-X画面が表示され、Open in Browserを押す。
MuleアプリケーションのPublic EndpointのURLをコピーする。
Advanced REST ClientにコピーしたURLをペーストし、末尾に宛先のエンドポイントを追加する。ヘッダー等に必要な入力をしてリクエストを送る。
例）コピーしたURL/api/reserve/restaurant/111
ローカルデプロイ同様、正常レスポンスおよびエラーレスポンスが返却される。

alt text

正常終了となるリクエスト

alt text

エラーとなるリクエスト

alt text

まとめ

いかがでしたでしょうか。本記事では以下の流れを説明しました。

API仕様をRAMLで作成
MockでAPI仕様の動作確認
APIをExchangeに公開
RAMLから実装スケルトンを自動生成
APIをローコードで実装＆デプロイ
APIの動作確認

今回説明できませんでしたが、以下のような機能も提供されています。

ローコード単体テストツール(MUnit)
APIカタログ(Exchange)
監視ツール(Monitoring)　等

このようにMuleSoftでは、API管理ツール、開発ツール、実行環境、運用ツールが提供されており、1つの製品でAPIのライフサイクルを一元管理することができます。
MuleSoftは無料トライアルが利用できるので、参考リンク集の【MuleSoftアカウント作成およびトライアル環境払出】からトライアルアカウントを作成して、いつでも自由に触れてみてください。

参考リンク集

【Anypoint Studioのダウンロード】
https://www.mulesoft.com/jp/platform/studio ⧉

【Advanced REST Clientのインストール】
https://install.advancedrestclient.com/ ⧉

【MuleSoftアカウント作成およびトライアル環境払出】
https://anypoint.mulesoft.com/login/signup?apintent=sfdc&_ga=2.134653110.616222964.1725270925-1555820403.1689237354 ⧉

【RAMLの言語仕様】
https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md ⧉

【MuleSoftのチュートリアル（日本語非対応）】
https://trailhead.salesforce.com/ja/users/strailhead/trailmixes/getting-started-with-anypoint-platform-dex-401 ⧉

記事をシェアする