メニュー
Amazon API Gateway
開発者ガイド

API を API Gateway にインポートする

API Gateway の API のインポート機能を使用して、外部の定義ファイルから API を API Gateway にインポートすることができます。現在、API のインポート機能では Swagger v2.0 定義ファイルがサポートされています。

API のインポートでは、ペイロードとして定義を含む POST リクエストを送信して新しい API を作成するか、ペイロードに定義を含む PUT リクエストを使用して既存の API を更新できます。新しい定義で上書きして API を更新したり、既存の API で定義をマージしたりします。mode クエリパラメーターを使用して、リクエスト URL でオプションを指定します。

注記

RAML API 定義の場合、引き続き API Gateway Importer を使用できます。

次に示すように、REST API への明示的な呼び出しを行うことに加えて、API Gateway コンソールで API のインポート機能を使用することもできます。このオプションは、[Actions] ドロップダウンメニューの項目として使用できます。API Gateway コンソールから API のインポート機能を使用する例については、「例から API Gateway API を作成する」を参照してください。

API のインポートを使用して新しい API を作成する

API のインポート機能を使用して新しい API を作成するには、API 定義ファイルを https://apigateway.<region>.amazonaws.com/restapis?mode=import に投稿します。このリクエストにより、新しい RestApi が作成され、リソースモデル、およびその他の項目が定義ファイルに定義されます。

次のコードスニペットは、JSON 形式の Swagger 定義のペイロードとともに POST リクエストの例を示しています。

Copy
POST /restapis?mode=import Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... Swagger API definition in JSON

API のインポートを使用して既存の API を更新する

ステージやステージ変数、または API キーから API への参照など、既存の API で保持したい側面がある場合、API のインポート機能を使用して、その API を更新することができます。

API の更新は、マージまたは上書きという 2 つのモードで行うことができます。API のマージは、外部の API 定義を複数の小さな部分に分解し、それらの部分の変更を一度に 1 つのみ適用する場合に役立ちます。たとえば、複数のチームが API のさまざまな部分を担当し、異なるレートで変更を可能にする場合です。このモードでは、インポートされた定義で明確に定義されていない既存の API の項目はそのままになります。

API の上書きは、外部の API 定義に、API の完全な定義が含まれているときに役立ちます。このモードでは、インポートされた定義で明確に定義されていない既存の API の項目は削除されます。

API をマージするには、PUT リクエストを https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=merge に送信します。restapi_id パスのパラメーター値は、指定された API 定義のマージ先となる API を示します。

次のコードスニペットは、指定された API がすでに API Gateway にあり、JSON の Swagger API 定義をペイロードとしてマージする PUT リクエストの例を示しています。

Copy
PUT /restapis/<restapi_id>?mode=merge Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... A Swagger API definition in JSON

更新オペレーションのマージでは、2 つの完全な API 定義を使用し、それらをマージします。小さい差分変更の場合は、リソースの更新オペレーションを使用できます。

API を上書きするには、PUT リクエストを https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=overwrite に送信します。restapi_id パスパラメーターは、指定された API 定義で上書きされる API を示します。

次のコードスニペットは、JSON 形式の Swagger 定義のペイロードでリクエストを上書きする例を示しています。

Copy
PUT /restapis/<restapi_id>?mode=overwrite Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... A Swagger API definition in JSON

mode クエリパラメーターが指定されていない場合、マージが想定されます。

注記

PUT オペレーションはべき等ですが、アトミックではありません。つまり、処理中にシステムエラーが発生した場合、API は不正な状態になる可能性があります。ただし、オペレーションを繰り返すと、API は最初のオペレーションが成功したかのように、最終的な同じ状態に移行します。

Swagger basePath

Swagger では、basePath プロパティを使用して、パスプロパティに定義された各パスに先行する 1 つ以上のパス部分を提供できます。API Gateway にはリソースのパスを表現するために複数の方法があるため、API のインポート機能には、インポート中に basePath プロパティを解釈するための 3 つのオプションが用意されています。

ignore

Swagger ファイルの basePath の値が "/a/b/c" で、paths プロパティに "/e" および "/f" が含まれる場合に、次の POST または PUT リクエストがあるとします。

Copy
POST /restapis?mode=import&basepath=ignore
Copy
PUT /restapis/api_id?basepath=ignore

この場合、API で次のリソースが発生します。

  • /

  • /e

  • /f

その効果として、basePath を、これが存在しなかったかのように扱い、宣言された API のすべてのリソースは、ホストに対して相対的に提供されます。これを使用できるのは、たとえば、基本パスを含まない API マッピングや、本番ステージを参照するステージ値を持つカスタムドメイン名がある場合です。

注記

API Gateway は、定義ファイルに明示的にされていない場合でも、自動的にルートリソースを作成します。

指定しない場合、basePath はデフォルトで ignore を受け取ります。

prepend

Swagger ファイルの basePath の値が "/a/b/c" で、paths プロパティに "/e" および "/f" が含まれる場合に、次の POST または PUT リクエストがあるとします。

Copy
POST /restapis?mode=import&basepath=prepend
Copy
PUT /restapis/api_id?basepath=prepend

この場合、API で次のリソースが発生します。

  • /

  • /自

  • /a/b

  • /a/b/c

  • /a/b/c/e

  • /a/b/c/f

その効果として、(メソッドなしで) 追加のリソースとして basePath を処理し、宣言されたリソースセットに追加します。これを使用できるのは、たとえば、さまざまなチームが API パートの異なる部分を担当し、basePath が各チームの API 部分のパスの場所を参照できる場合です。

注記

API Gateway は、定義に明示的に宣言されていない場合でも、自動的に中間リソースを作成します。

split

Swagger ファイルの basePath の値が "/a/b/c" で、paths プロパティに "/e" および "/f" が含まれる場合に、次の POST または PUT リクエストがあるとします。

Copy
POST /restapis?mode=import&basepath=split
Copy
PUT /restapis/api_id?basepath=split

この場合、API で次のリソースが発生します。

  • /

  • /b

  • /b/c

  • /b/c/e

  • /b/c/f

その効果として、最上位のパス部分 "/a" を、各リソースのパスの先頭として扱い、API 内で (メソッドなしで) 追加のリソースを作成します。これを使用できるのは、たとえば、"a" が、API の一部として公開するステージ名である場合です。

インポート中のエラー

インポート中に、無効な Swagger ドキュメントなど、大きな問題に対してエラーが生成される場合があります。エラーは、失敗のレスポンスの例外 (例: BadRequestException) として返されます。エラーが発生した場合、新しい API 定義は破棄され、既存の API は変更されません。

インポート中の警告

インポート中に、モデル参照の不足など、小規模な問題に対して警告が生成される場合があります。警告が発生した場合、リクエスト URL に failonwarnings=false クエリ式が追加されている場合、オペレーションは続行します。それ以外の場合、更新はロールバックされます。デフォルトで、failonwarningsfalse に設定されています。このような場合、警告は RestApi リソースのフィールドとして返されます。それ以外の場合、警告は例外のメッセージとして返されます。