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 アカウントの作成の説明に従って登録できます。
  • 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 プロキシの作成

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 プロキシがデプロイされる環境、この [Proxy Base Path] で構成されます。たとえば、http://myorg-test.apigee.net/mock-target-api です。 すべて小文字に変換された、[Proxy Name] 項目の内容
    Existing API この API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。たとえば、http://mocktarget.apigee.net です。 OpenAPI 仕様のプロパティが次のように組み合わされてターゲット URL が作成されます。
    • http:// または https://schemes プロパティに基づく)
    • host プロパティ
    • basePath プロパティ(指定された場合)
    Description API プロキシの説明。 description プロパティ

    以下に示す OpenAPI 仕様からの抜粋では、フィールドに事前入力するために使われるプロパティが示されています。

        swagger: '2.0'
        info:
          description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
          version: 1.0.0
          title: Mock Target API
        host: mocktarget.apigee.net
        schemes:
          - http
          - https
        ...
    
        
  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] ページを表示させます。
    模擬 Target 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 ポリシーを追加する

次に、API プロキシを OpenAPI 仕様から作成したときに自動的に生成された [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 管理 API の [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"}}
    

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