API 仕様の反復的な設計と実装

logo desktop IDE Desktop IDE

これは進行中のベータリリースです。ベータ状態での Anypoint Code Builder の使用には、該当するベータサービス契約条件が適用されます。

API 仕様を IDE 内の実装プロジェクトにスキャフォールディングして、仕様への変更を最初に Anypoint Exchange にパブリッシュすることなくインターフェースと同期します。たとえば、新しいエンドポイントを API 仕様に追加したら、その変更をインターフェースに再スキャフォールディングして、そのエンドポイントのフローをインターフェースの設定 XML ファイルに追加できます。

インターフェース XML は、スキャフォールディングプロセス中に Mule プロジェクトに自動的に作成されます。API を API 設計プロジェクト内の仕様ファイルで定義します。

IDE 内での反復的な API 設計と実装は、VS Code のマルチルートワークスペースで実行されます。API 仕様および実装プロジェクトのプロジェクトフォルダーをマルチルートワークスペースにマッピングするため、VS Code では拡張子 .code-workspace 付きのファイルが使用されます。プロジェクトを適切に動作させるには、このファイルはどちらのプロジェクトフォルダーにも存在してはなりません。また、Anypoint Code Builder では、反復的な設計フォルダーと実装プロジェクトフォルダーのペアがマルチルートワークスペースごとに 1 つのみ許可されます。仕様および実装プロジェクトを作成するための手順は次の要件を満たすように設計されています。VS Code ドキュメントで情報を確認するには、「Multi-root Workspaces (マルチルートワークスペース)」を参照してください。

現在、この手順はデスクトップ IDE のみを対象として記載されています。

始める前に

MuleSoft 環境をセットアップします。詳細は、Anypoint Code Builder の使用開始を参照してください。

API 仕様を作成する

デスクトップ IDE で Cmd+Shift+n (Mac) または Ctrl+Shift+n (Windows) を押して、VS Code で新しいウィンドウを開きます。

このステップにより、反復的な設計および実装プロジェクトがすでに含まれているマルチルートワークスペースに API 仕様を作成できなくなり、次の手順 (ローカル API 仕様をインターフェースにスキャフォールディングする) で必要なコマンドが使用できるようになります。
デスクトップ IDE のアクティビティバーで ([Anypoint Code Builder]) アイコンをクリックして Anypoint Code Builder を開きます。
クイックアクション [Design an API (API を設計)] をクリックして、API 仕様を開始します。

または、Ctrl+Shift+p (Mac) または Cmd+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Design an API
```
プロンプトが表示されたら、Anypoint Platform にサインインし、すべてのプロンプトに従って IDE を再開します。

API 仕様を開始します。

1	[Project name (プロジェクト名)] に「Retrieve Users API」 (ユーザーの取得 API) と入力します。名前は一意である必要があります。
2	[Project Location (プロジェクトの場所)] で [Browse (参照)] をクリックします。デスクトップ IDE で開かれた [File (ファイル)] メニューで、`workspace-retrieve-users` などのフォルダーを作成し、フォルダーの場所を選択します。完了したら、[Project Location (プロジェクトの場所)] 項目のフルパスは `/Users/me/workspace-retrieve-users` のようになります。新しいフォルダーを含むディレクトリから開始することで、マルチルートワークスペースに関連する潜在的な問題が回避されます。
3	[API Specification Language (API 仕様言語)] で [RAML 1.0] を選択します。
4	[Business Group (ビジネスグループ)] で、API 仕様のビジネスグループを選択します。API 仕様の作成後にビジネスグループを変更することはできません。詳細は、「ビジネスグループ」を参照してください。

完了したら、[Design an API (API を設計)] は次の例のようになります。

[Create Project (プロジェクトを作成)] をクリックします。

このプロセスでは、API 仕様を含むプロジェクトがワークスペース内に作成されます。
API 仕様ファイル (retrieve-users-api.raml) を開きます。
内部プロセスの進行状況を追跡するには、[Mule DX Server (Mule DX サーバー)] への [Output (出力)] パネルを開きます。
手順を表示
Cmd+Shift+u (Mac) または Ctrl+Shift+u (Windows) を押して [Output (出力)] パネルを開きます。

パネルのドロップダウンメニューから [Mule DX Server] を選択します。

詳細は、出力パネルを開くを参照してください。

API 仕様のエディターで次の例を retrieve-users-api.raml に追加します。

#%RAML 1.0
title: Retrieve Users API
version: 1.0.development
/users:
  get:
    description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:
            example: |
              [{
              "id": 1,
              "name": "Leanne Graham",
              "username": "Bret",
              "email": "Sincere@april.biz",
              "address": {
                "street": "Kulas Light",
                "suite": "Apt. 556",
                "city": "Gwenborough",
                "zipcode": "92998-3874",
                "geo": {
                  "lat": "-37.3159",
                  "lng": "81.1496"
                }
              },
              "phone": "1-770-736-8031 x56442",
              "website": "hildegard.org",
              "company": {
                "name": "Romaguera-Crona",
                "catchPhrase": "Multi-layered client-server neural-net",
                "bs": "harness real-time e-markets"
              } }]

ローカル API 仕様をインターフェースにスキャフォールディングするに進みます。

ローカル API 仕様をインターフェースにスキャフォールディングする

ローカル API 仕様をローカル実装プロジェクトにスキャフォールディングします。スキャフォールディングプロセスにより実装の設定 XML が作成されます。

プロジェクトがデスクトップ IDE にあるか Anypoint Platform 内のユーザーアカウントに関連付けられたクラウド IDE にあるかにかかわらず、ローカルプロジェクトは Anypoint Code Builder IDE に存在します。

ローカル API 仕様をスキャフォールディングする手順は、次のとおりです。

IDE で retrieve-users-api.raml を開いて、仕様を Mule プロジェクトにスキャフォールディングする準備を整えます。

アクティビティバーで ([Implement this local API (このローカル API を実装)]) アイコンをクリックします。

または、Cmd+Shift+p (Mac) または Ctrl+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Implement this Local API
```
コマンド [MuleSoft: Implement an API Specification (Mulesoft: API 仕様を実装する)] を選択しないでください。これは、Anypoint Exchange にパブリッシュする仕様を実装するコマンドであり、ローカル API 仕様を実装するコマンドではありません。

UI にメッセージ [We’ll create a workspace to keep your API specification and Mule project in sync (API 仕様と Mule プロジェクトの同期を維持するためのワークスペースを作成します)] が表示されたら [OK] をクリックします。

マルチワークスペースの拡張子 .code-workspace 付きのファイルを保存するように促すプロンプトで、このファイルを API 仕様プロジェクトフォルダー内に保存しないでください。代わりに、次のステップに進みます。

ワークスペース用に作成した親フォルダーまで移動して .code-workspace ファイルを保存します。
[Output (出力)] パネルで [Mule DX Server (Mule DX サーバー)] 出力を使用して内部プロセスの進行状況を追跡できることを確認します。

UI にメッセージ [Implementing local API implementation, please wait. (ローカル API 仕様を実装しています。お待ちください。)] が表示されます。

出力を監視しながら、プレースホルダーテキスト [Mule project name (Mule プロジェクト名)] を含む項目が UI に表示されるまで待ちます。次に例を示します。

Mule 実装プロジェクトの名前 (retrieve-users-implementation など) を入力して、スキャフォールディングプロセスを開始します。
プロンプトが表示されたら、[Select target folder (対象フォルダーを選択)] をクリックします。

対象フォルダーは、API 仕様が作成されたプロジェクトフォルダーです。

スキャフォールディングプロセスが実行されている間、UI で更新情報が提供されます。
- Executing scaffolding operation, please wait (スキャフォールディング操作を実行しています。お待ちください)
- Scaffolding process ended. You can now start iterating over your local API and implementation project (スキャフォールディングプロセスが終了しました。ローカル API および実装プロジェクトの反復を開始できるようになりました)

[Explorer] のマルチルートワークスペースから、新しい Mule プロジェクトでスキャフォールディング済み仕様が開きます。

実装用の設定 XML ファイル (retrieve-users-implementation.xml) は、次のような実装プロジェクトディレクトリに配置されています。

retrieve-users-implementation/src/main/mule/retrieve-users-implementation.xml

この Mule プロジェクトのキャンバス UI には Router コンポーネントといくつかのエラーハンドラーが含まれます。APIkit によりこれらのコンポーネントはスキャフォールディングプロセス中に自動的に作成されます。

実装 XML のフロー <flow name="get:\users:retrieve-users-api-config"> には、例を含む <ee:transform/> 要素が含まれます。

<flow name="get:\users:retrieve-users-api-config">
    <ee:transform doc:name="Transform Message">
        <ee:message>
            <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
[
{
id: 1,
name: "Leanne Graham",
username: "Bret",
email: "Sincere@april.biz",
address: {
  street: "Kulas Light",
  suite: "Apt. 556",
  city: "Gwenborough",
  zipcode: "92998-3874",
  geo: {
    lat: "-37.3159",
    lng: "81.1496"
  }
},
phone: "1-770-736-8031 x56442",
website: "hildegard.org",
company: {
  name: "Romaguera-Crona",
  catchPhrase: "Multi-layered client-server neural-net",
  bs: "harness real-time e-markets"
}
}
]]]></ee:set-payload>
        </ee:message>
    </ee:transform>
</flow>

API 仕様を更新して実装 XML を再スキャフォールディングするに進みます。

API 仕様を更新して実装 XML を再スキャフォールディングする

エンドポイントを仕様ファイルに追加して、再スキャフォールディングします。

[Explorer] で [Retrieve Users API (ユーザーの取得 API)] ディレクトリの仕様ファイル retrieve-users-api.raml に移動します。

次の /userbyid エンドポイント設定を RAML ファイルに追加します。

#%RAML 1.0
title: Retrieve User
version: 1.0.development
/users:
  get:
    description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:
            example: |
              [{
              "id": 1,
              "name": "Leanne Graham",
              "username": "Bret",
              "email": "Sincere@april.biz",
              "address": {
                "street": "Kulas Light",
                "suite": "Apt. 556",
                "city": "Gwenborough",
                "zipcode": "92998-3874",
                "geo": {
                  "lat": "-37.3159",
                  "lng": "81.1496"
                }
              },
              "phone": "1-770-736-8031 x56442",
              "website": "hildegard.org",
              "company": {
                "name": "Romaguera-Crona",
                "catchPhrase": "Multi-layered client-server neural-net",
                "bs": "harness real-time e-markets"
              } }]
  /userbyid:
    get:
      description: Get information about a particular user
      queryParameters:
        id:
          description: Specify the id of the user you want to retrieve
          type:        integer
          required:    false
          example: 3
      responses:
        200:
          body:
            application/json:
              example: |
                [{
                "id": 3,
                "name": "Clementine Bauch",
                "username": "Samantha",
                "email": "Nathan@yesenia.net",
                "address": {
                  "street": "Douglas Extension",
                  "suite": "Suite 847",
                  "city": "McKenziehaven",
                  "zipcode": "59590-4157",
                  "geo": {
                    "lat": "-68.6102",
                    "lng": "-47.0653"
                  }
                },
                "phone": "1-463-123-4447",
                "website": "ramiro.info",
                "company": {
                  "name": "Romaguera-Jacobson",
                  "catchPhrase": "Face to face bifurcated interface",
                  "bs": "e-enable strategic applications"
                } }]

API 仕様を再スキャフォールディングして Mule プロジェクトを更新します。

Cmd+Shift+p (Mac) または Ctrl+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Re-scaffold this local API
```

プロジェクトが正常にスキャフォールディングされたことを示すメッセージを受け取ったら、実装 XML ファイルに移動して、userbyid エンドポイントの新しいフロー (<flow name="get:\users\userbyid:design-an-api-config"/>) を確認します。

...

<flow name="get:\users\userbyid:retrieve-users-api-config">
    <ee:transform doc:name="Transform Message">
        <ee:message>
            <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
[
{
id: 3,
name: "Clementine Bauch",
username: "Samantha",
email: "Nathan@yesenia.net",
address: {
  street: "Douglas Extension",
  suite: "Suite 847",
  city: "McKenziehaven",
  zipcode: "59590-4157",
  geo: {
    lat: "-68.6102",
    lng: "-47.0653"
  }
},
phone: "1-463-123-4447",
website: "ramiro.info",
company: {
  name: "Romaguera-Jacobson",
  catchPhrase: "Face to face bifurcated interface",
  bs: "e-enable strategic applications"
}
}
]]]></ee:set-payload>
        </ee:message>
    </ee:transform>
</flow>

API 仕様を Design Center に保存するに進みます。

API 仕様を Design Center に保存する

API 仕様を実装したら、仕様を Design Center に保存します。

[Source Control (ソース制御)] パネルを開きます。
手順を表示
アクティビティバーの (Source Control (ソース制御)) アイコンをクリックするか、キーボードショートカットを使用する。
- Mac: Ctrl+Shift+g
- Windows: Cmd+Shift+g
retrieve-users-api.raml の API 仕様プロジェクトを見つけます。
[Source Control (ソース制御)] ビューで [Changes (変更)] 見出しにマウスポインターを置いて [+] (プラス) アイコンを表示し、そのアイコンをクリックすることで、変更をステージングします。
「Retrieve Users Projects」 (ユーザーの取得プロジェクト) など、変更の概要を示すコミットメッセージを入力します。

このステップにより、IDE に表示される個別のファイルを介してコミットメッセージを指定する必要がなくなります。
ステージング済みの変更で [Commit (コミット)] をクリックし、コミットプロセスが完了するまで待機します。
プロンプトが表示されたら、[Sync Changes (変更を同期)] または [Push (プッシュ)] をクリックします。

変更が Design Center SCM に保存されました。
API 仕様を Exchange にパブリッシュするに進みます。

API 仕様を Exchange にパブリッシュする

変更を Design Center にコミットしたら、API 仕様を Anypoint Exchange にパブリッシュして、チームメンバーがその仕様を見つけることができるようにします。

コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。

次のコマンドを入力します。

MuleSoft: Publish API Specification to Exchange

プロジェクト名を入力します: Retrieve Users API (ユーザーの取得 API)
アーティファクト ID を確認します: Retrieve-Users-API
アセットバージョンを確認します: 1.0.0
API バージョンを確認します: v1

API 仕様の v1.0.0 を参照するように Mule プロジェクトの POM ファイルが IDE で更新されるまで、ステータスバーに進行状況関連のメッセージが表示されます。
- Publishing API Specification to Exchange (API 仕様を Exchange にパブリッシュしています)
- Project has been successfully published to Exchange (プロジェクトが Exchange に正常にパブリッシュされました)

ビジネスグループのチームメンバーはこの仕様を Anypoint Exchange で入手してプロジェクトと実装にスキャフォールディングできるようになりました。API 仕様を Exchange からスキャフォールディングするを参照してください。

API 仕様を Exchange からスキャフォールディングする

ビジネスグループのチームメンバーは API 仕様を Exchange からインポートできます。

新しい VS Code インスタンスを開きます。
API のバージョン 1.0.0 を Design Center からインポートします。
1. コマンドパレットを開きます。
  手順を表示
  キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
  
  デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
  
  クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
2. 次のコマンドを入力します。
  MuleSoft: Implement an API Specification (MuleSoft: API 仕様を実装する)
3. 開いている [Implement an API Specification (API 仕様を実装する)] タブで次の操作を実行します。
  - 実装の新しい名前を入力します。
  - 新しいプロジェクトの場所を選択または作成します。
  - Anypoint Exchange で API 仕様を見つけて [Add (追加)] をクリックし、API 参照名を項目に挿入します。
4. [Create Project (プロジェクトを作成)] をクリックして、新しい実装への仕様のスキャフォールディングを開始します。
スキャフォールディング済み仕様を IDE に実装します。

マルチルートワークスペースを閉じる

コマンド [Workspaces: Close Workspace (ワークスペース: ワークスペースを閉じる)] を使用してマルチルートワークスペースを作成します。

閉じた後、同期されたプロジェクトを、API の実装時に作成したワークスペースから再度開くことができます。

マルチルートワークスペースを開く

ワークスペースのプロジェクトの .code-workspace ファイル (Retrieve Users API.code-workspace など) からマルチルートワークスペースを開きます。

VS Code を開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
次のコマンドを入力します。
```
File: Open Workspace from File...
```
ワークスペースのプロジェクトの .code-workspace ファイルに移動してダブルクリックします。

[Explorer] ビューでプロジェクトが開きます。マルチルートワークスペースの見出しには [(WORKSPACE)] 識別子が追加されます。次に例を示します。

1	[Project name (プロジェクト名)] に「Retrieve Users API」 (ユーザーの取得 API) と入力します。名前は一意である必要があります。
2	[Project Location (プロジェクトの場所)] で [Browse (参照)] をクリックします。デスクトップ IDE で開かれた [File (ファイル)] メニューで、`workspace-retrieve-users` などのフォルダーを作成し、フォルダーの場所を選択します。完了したら、[Project Location (プロジェクトの場所)] 項目のフルパスは `/Users/me/workspace-retrieve-users` のようになります。新しいフォルダーを含むディレクトリから開始することで、マルチルートワークスペースに関連する潜在的な問題が回避されます。
3	[API Specification Language (API 仕様言語)] で [RAML 1.0] を選択します。
4	[Business Group (ビジネスグループ)] で、API 仕様のビジネスグループを選択します。API 仕様の作成後にビジネスグループを変更することはできません。詳細は、「ビジネスグループ」を参照してください。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan