OpenAPI 仕様から API プロキシを作成する

演習内容

このチュートリアルでは、以下のことを学びます。

  • OpenAPI 仕様からの Edge API プロキシの作成
  • cURL を使用した API プロキシの呼び出し
  • 条件付きフローにポリシーを追加する
  • cURL を使用したポリシー呼び出しのテスト

このチュートリアルでは、Apigee Edge 管理 UI を使って OpenAPI 仕様から Edge API プロキシを作成する方法について学習します。cURL などの HTTP クライアントで API プロキシを呼び出す際、API プロキシはリクエストを Apigee 疑似ターゲット サービスに送信します。

Open API Initiative について

Open API Initiative
「Open API Initiative(OAI)は、Swagger 仕様に基づく、ベンダーに依存しない API 記述形式の作成、進化、促進に注力しています。」Open API Initiative について詳しくは、https://openapis.org をご覧ください。

OpenAPI 仕様では、標準的な形式を使用して RESTful API を記述します。JSON または YAML 形式で記述された OpenAPI 仕様は、マシン可読でありながら、人間も簡単に読んで理解できます。この仕様は、ベースパス、パスと動詞、ヘッダー、クエリ パラメータ、オペレーション、コンテンツ タイプ、レスポンス記述などの API の要素を記述しています。また、OpenAPI 仕様は API ドキュメントの生成にもよく使用されます。

Apigee 疑似ターゲット サービスについて

このチュートリアルで使用される Apigee 疑似ターゲット サービスは、Apigee でホストされ、単純なデータを返します。API キーやアクセス トークンは必要ありません。実際に、ウェブブラウザでアクセスできます。次をクリックして、試してみましょう。

http://mocktarget.apigee.net

ターゲット サービスからあいさつ Hello, guest! が返ってきます。

疑似ターゲット サービスがサポートする完全な API の一覧については、次の URL をクリックしてください。

http://mocktarget.apigee.net/help

必要なもの

  • Apigee Edge アカウント。Apigee Edge のアカウントがない場合は、Apigee Edge アカウントの作成に沿って登録できます。
  • OpenAPI 仕様。このチュートリアルでは、Apigee の疑似ターゲット サービス http://mocktarget.apigee.net を記述した mocktarget.yaml OpenAPI 仕様を使用します。詳しくは、https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi をご覧ください。
  • cURL。コマンドラインまたはウェブブラウザから API 呼び出しを行うために、マシンにインストールされている必要があります。

API プロキシの作成

Edge

Edge UI を使用して OpenAPI 仕様から API プロキシを作成するには:

  1. https://apigee.com/edge にログインします。
  2. メイン ウィンドウで [API Proxies] をクリックします。

    左側のナビゲーション バーで [Develop] > [API Proxies] を選択することもできます。

    ランディング ページの [API Proxies] をクリック

  3. [+ Proxy] をクリックします。
    API プロキシの追加
  4. [Create Proxy] ウィザードで、[Reverse proxy (most common)] テンプレートの [Use OpenAPI Spec] をクリックします。
    プロキシタイプの作成
  5. [Import from URL] をクリックしてから、次の情報を入力します。
    • OpenAPI Spec URL: [URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツへのパスを入力します。
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Spec name: OpenAPI 仕様の名前(Mock Target など)を入力します。

      この名前は、OpenAPI 仕様を仕様ストアに保存するために使用されます。仕様を管理するをご覧ください。

  6. [Import] をクリックします。

    [Create Proxy] ウィザードの [Details] ページが表示されます。以下に示すように、OpenAPI 仕様で定義されている値がフィールドに事前入力されます。

    次の表に、OpenAPI 仕様のプロパティを使用して事前に入力されるデフォルト値を示します。表の後に、使用されるプロパティを示す OpenAPI 仕様の抜粋を示します。

    フィールド 説明 デフォルト
    Name API プロキシの名前。例: Mock-Target-API OpenAPI 仕様の title プロパティ(スペースはダッシュに置き換えられる)
    Base path 組織内で API プロキシを一意に識別するパス コンポーネント。API プロキシの一般公開される URL は、組織名、この API プロキシがデプロイされる環境、このベースパスで構成されます。例: http://myorg-test.apigee.net/mock-target-api [Name] フィールドの内容(すべて小文字に変換される)
    Description API プロキシの説明。 OpenAPI 仕様の description プロパティ
    Target (Existing API) API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。例: http://mocktarget.apigee.net OpenAPI 仕様の servers プロパティ

    次の OpenAPI 仕様からの抜粋に、フィールドへの事前入力に使用されるプロパティを示します。

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  7. [Description] フィールドを次のように編集します。API proxy for the Apigee mock target service endpoint.
  8. [Next] をクリックします。
  9. [Common policies] ページで、[Security: Authorization] の [Pass through (no authorization)] が選択されていることを確認してから、[Next] をクリックします。

    [Common policies] ページで [Pass through (no authorization)] が選択されている

  10. [Flows] ページで、すべてのオペレーションが選択されていることを確認します。プロキシフローの作成
  11. [Next] をクリックします。
  12. [Virtual hosts] ページで [default] と [secure] を選択してから、[Next] をクリックします。
    [Virtual hosts] ページで選択された default と secure
  13. [Summary] ページの [Optional Deployment] で [Test] 環境が選択されていることを確認してから、[Create and deploy] をクリックします。

    Apigee によって新しい API プロキシが作成され、テスト環境にデプロイされます。

  14. [Edit proxy] をクリックして、API プロキシの [Overview] ページを表示します。
    疑似ターゲット API プロキシのサマリー

Classic Edge(Private Cloud)

Classic Edge UI を使用して OpenAPI 仕様から API プロキシを作成するには:

  1. https://apigee.com/edge にログインします。
  2. メイン ウィンドウで [API Proxies] をクリックします。

    左側のナビゲーション バーで [Develop] > [API Proxies] を選択することもできます。

  3. [+ Proxy] をクリックします。
    API プロキシの追加
  4. [Create Proxy] ウィザードで [Reverse proxy (most common)] を選択して、[Use OpenAPI] をクリックします。
    プロキシタイプの作成
  5. [Import from a URL] をクリックして OpenAPI 仕様の名前を入力します。[URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツのパスを入力します。

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. [Select] をクリックします。
  7. [Next] をクリックします。

    [Create Proxy] ウィザードの [Details] ページが表示されます。次の図に示すように、OpenAPI 仕様で定義された値がフィールドに事前入力されます。

    プロキシの詳細の作成

    次の表に、OpenAPI 仕様のプロパティを使用して事前に入力されるデフォルト値を示します。表の後に、使用されるプロパティを示す OpenAPI 仕様の抜粋を示します。

    フィールド 説明 デフォルト
    Proxy Name API プロキシの名前。例: Mock-Target-API OpenAPI 仕様の title プロパティ(スペースはダッシュに置き換えられる)
    Proxy Base Path 組織内で API プロキシを一意に識別するパス コンポーネント。API プロキシの一般公開される URL は、組織名、この API プロキシがデプロイされる環境、このベースパスで構成されます。例: http://myorg-test.apigee.net/mock-target-api [Name] フィールドの内容(すべて小文字に変換される)
    Existing API API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。例: http://mocktarget.apigee.net OpenAPI 仕様の servers プロパティ
    Description API プロキシの説明。 OpenAPI 仕様の description プロパティ

    次の OpenAPI 仕様からの抜粋に、フィールドへの事前入力に使用されるプロパティを示します。

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  8. [Description] フィールドを次のように編集します。API proxy for the Apigee mock target service endpoint.
  9. [Next] をクリックします。
  10. [Flows] ページで、すべてのオペレーションが選択されていることを確認します。プロキシフローの作成
  11. [Next] をクリックします。
  12. [Security] ページで、セキュリティ オプションとして [Pass through (none)] を選択してから、[Next] をクリックします。
  13. [Virtual Hosts] ページで、すべての仮想ホストが選択されていることを確認してから、[Next] をクリックします。
  14. [Build] ページで test 環境が選択されていることを確認してから、[Build and Deploy] をクリックします。
  15. [Summary] ページに、新しい API プロキシが正常に作成され、test 環境にデプロイされたことを示す確認応答が表示されます。
    プロキシ サマリーの作成
  16. [Mock-Target-API] をクリックして、API プロキシの [Overview] ページを表示します。
    疑似ターゲット API プロキシのサマリー

これで完了ですOpenAPI 仕様から API プロキシを作成できました。次は、その動作をテストします。

API プロキシのテスト

ここでは、cURL またはウェブブラウザを使用して、Mock-Target-API API のテストを行います。

ターミナル ウィンドウで、次の cURL コマンドを実行します。URL 内の組織名はご自分の組織名に置き換えてください。

curl http://<org_name>-test.apigee.net/mock-target-api

レスポンス

次のようなレスポンスが表示されます。

Hello, Guest!

成功です。簡単な API プロキシを OpenAPI 仕様から構築し、テストできました。

XML to JSON ポリシーを追加する

次に、OpenAPI 仕様から API プロキシを作成したときに自動的に生成された View XML Response 条件付きフローに XML to JSON ポリシーを追加します。このポリシーは、ターゲットの XML レスポンスを JSON レスポンスに変換します。

最初に、ポリシーの追加後に受け取る結果と元の結果を比較できるように、API を呼び出します。ターミナル ウィンドウで、次の cURL コマンドを実行します。ターゲット サービスの /xml リソースを呼び出します。これにより、ネイティブに XML の単純なブロックが返されます。URL 内の組織名はご自分の組織名に置き換えてください。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

レスポンス

次のようなレスポンスが表示されます。

<root>
  <city>San Jose</city>
  <firstName>John</firstName>
  <lastName>Doe</lastName>
  <state>CA</state>
</root>

次に、XML レスポンスを JSON に変換してみましょう。XML to JSON ポリシーを API プロキシの [View XML Response] 条件付きフローに追加します。

  1. Edge UI で、[Mock-Target-API] の [Overview] ページの右上にある [Develop] タブをクリックします。
    [Developer] タブ
  2. 左側の [Navigator] ナビゲーション パネルの [Proxy Endpoints] > [default] で、[View XML Response] 条件付きフローをクリックします。
    [View XML Response] の選択
  3. 画面下部で、フローの [Response] に対応する [+ Step] ボタンをクリックします。
    [+Step] の選択
    [Add Step] ダイアログが開き、追加できるすべてのポリシーの分類リストが表示されます。
  4. [Mediation] カテゴリまでスクロールし、[XML to JSON] を選択します。
    [Add Step] ダイアログ
  5. [Display Name] と [Name] はデフォルト値のままにします。
  6. [Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。フローの XML to JSON ポリシー
  7. [Save] をクリックします。

ポリシーを追加したら、cURL を使用して API をもう一度呼び出します。同じ /xml リソースを呼び出していることに注意してください。ターゲット サービスは依然として XML のブロックを返しますが、API プロキシのポリシーはレスポンスを JSON に変換します。次の呼び出しを行います。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

XML レスポンスが JSON に変換されていることに注目してください。

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

これで完了です条件付きフローに追加したポリシーの実行を正常にテストできました。