ステップ 2.API 仕様の設計
API 仕様と API
API とは、特定のリソースにアクセスするためにパブリッシュされたインターフェースであり、正しい権限と適切な構造の要求を使用することでリソースにアクセスできるようにします。
API 仕様とは、API の機能と予期される動作、そして設計の基本理念やサポートされるデータ型などの詳細を定義したものです。 API 仕様にはドキュメントと API 定義が含まれ、人間とソフトウェアが読むことのできるコントラクトを作成します。
MuleSoft は、API 仕様の作成を容易にするツールを提供しています。作成した API 仕様は、チーム、顧客、一般の人々と共有できます。 API 仕様を利用することで、API の採用が促進され、プロジェクトをより早く完了できるようになります。
ステップ 2.1: 既存の API 仕様を調査する
自分で API 仕様を作成する前に、既存の API 仕様を参考にすることで、自分と似たような状況に対して他の人々がどのようなアプローチを採ったかを学習できます。 また、同じ目的の API 仕様がすでに存在するかどうかを調べて、その API 仕様が適切であれば再利用できます。
必要な処理をすでに実装している API 仕様は、簡単に探すことができます。
-
公開 Exchange を確認します。公開 Exchange とは、MuleSoft がホストしているポータルであり、API 仕様やコネクタなど、さまざまな公開アセットをダウンロードして使用できます。 最もよく利用されている API 仕様、コネクタ、および他のアセットは、ランディングページに表示されています。
-
[Any Type (任意の種別)] > [REST APIs (REST API)] を選択して、REST API 仕様のみを表示します。
-
いずれかの仕様をクリックして、その API に対して定義されているデータ型と HTTP 要求を表示します。
-
-
自分の組織 (アカウント) の Exchange を確認します。ログインすると、表示が自分の組織の非公開 Exchange に変わります。
-
必要であれば Anypoint Platform にログインします。
-
Anypoint Platform ランディングページで、[Exchange] セクションに移動して [Discover and share (検出して共有)] をクリックします。
-
いずれかの仕様をクリックして、その API に対して定義されているデータ型と HTTP 要求を表示します。トライアル組織の場合は、まだ何も表示されない場合があります。
-
Exchange で使用可能ないくつかのアセットを調査したら、Anypoint Platform に戻り、新しい API 仕様を Web ベースツールで作成します。
ステップ 2.2: 自分の API 仕様を作成する
GET 要求に応答するシンプルな Hello World API の独自の API 仕様を作成します。 これを行うには、Design Center に含まれる API Designer を使用します。
-
API Designer を開きます。
-
[Create (作成)] > [New API Specification (新しい API 仕様)] を選択して API Designer エディターを開きます。
-
[New API specification (新しい API 仕様)] ダイアログで、[Project Name (プロジェクト名)] に
hello-world-api と入力し、他のデフォルト値は変更せずに [Create API (API を作成)] をクリックします。API Designer エディターにサンプル RAML 定義が表示されます。
-
既存のテキストを削除して、次の RAML をコピーして貼り付けます。
#%RAML 1.0
title: hello world
version: v1
description: A greeting for the world
types:
greeting:
properties:
todays-greeting: string
/greeting:
get:
responses:
200:
body:
application/json:
type: greeting
example:
{todays-greeting: "test-greeting"}
404:
body:
application/json:
properties:
message: string
example: |
{
"message" : "Greeting not found"
}この API 仕様には以下が含まれます。
-
単一の HTTP 要求 (GET)
-
単一のプロパティ (
todays-greeting) とサンプル値を持つ単一のデータ型 (greeting) -
HTTP 成功応答
-
HTTP エラー応答
ステップ 2.3: API 仕様をテストする
今度は、モッキングサービスを使用して要求を送信し、hello-world-api API 仕様をテストします。モッキングサービスは、API 仕様に基づいて有効なエンドポイントを作成し、認証、リクエストヘッダー、レスポンスヘッダーを管理するためのシンプルな UI を提供します。
API 仕様をテストする手順は次のとおりです。
-
hello-world-api.raml が開いてなければ開きます。
-
[Documentation (ドキュメント)] パネルが開いていない場合は、ドキュメントアイコンをクリックします。
-
API endpoints という表示ラベルを探します。定義したエンドポイントが表示されます。HTTP 要求は緑色のボックスに表示されます。
-
[GET] をクリックして、GET 要求と仕様の詳細情報を表示します。
-
[Show (表示)] をクリックして、各プロトコルのコード例を確認します。
-
[200] タブと [404] タブをクリックして、API 仕様で定義されている応答を確認します。
-
[Try It (試す)] ボタンをクリックします。
-
[Send (送信)] をクリックして、モッキングサービスが仕様に基づいて作成した一時的な要求 URL に要求を送信します。
この画面に表示されるエラーメッセージは無視しても構いません。要求が成功すると
200 OK とテストメッセージが返されます。
-
その他 (…) メニューの [Response details (レスポンス詳細)] を選択して、モッキングサービスのレスポンスヘッダーやリクエストヘッダーを調べれば、問題を診断したり、API 仕様の動作を理解することができます。
-
テストが終了したら、[Mocking Service Configuration (モッキングサービス設定)] パネルを開きます。
-
[Local Settings (ローカル設定)] で、[Select By Default (デフォルトで選択)] を有効にします。
ステップ 2.4.API 仕様をパブリッシュする
API をテストしたら、API を非公開 Exchange にパブリッシュして、組織内の他のユーザーがこの API を再利用できるようにします。
-
hello-world-api.raml が開いてなければ開きます。 -
[Publish (パブリッシュ)] をクリックします。
-
[Publishing to Exchange (Exchange へのパブリッシュ)] ダイアログで、デフォルトを受け入れて [Publish to Exchange (Exchange にパブリッシュ)] をクリックします。
-
確認ダイアログで [Close (閉じる)] をクリックします。
パブリッシュ後は、組織内のすべてのユーザーに hello-world-api API 仕様が表示され、再利用できるようになります。
次のステップ
API を設計してその API 仕様を作成したところで、次は Anypoint Studio (Studio) を使用して、API の実装とインターフェースを含む Mule アプリケーションを作成します。
開発者向けの詳細
詳細に興味がある場合は以下を参照してください。
詳細: Exchange
アセットは、公開 Exchange、内部 Exchange、または公開開発者ポータルでパブリッシュできます。
-
公開 Exchange に加えて、組織の内部のみで提供されているアセットも確認できます。
-
公開開発者ポータルを作成してある場合は、[Public portal (公開ポータル)] をクリックしてポータルでアセットを確認できます。
開発者とパートナー向けの詳細
API 仕様を共有してサポートするため、次のバージョンに向けて API 仕様に関するフィードバックを集めましょう。