Amazon API Gateway
開発者ガイド

Swagger ファイルをインポートして既存の API 定義を更新する

エンドポイント設定、ステージおよびステージ変数、または API キーへの参照を変更せずに、既存の API を更新するだけで、API 定義をインポートすることができます。

インポートから更新への操作は、マージまたは上書きという 2 つのモードで行うことができます。

API (A) が別の API (B) にマージされると、作成された API では、2 つの API で矛盾する定義が共有されていない限り、AB の両方の定義が保持されます。矛盾が発生した場合、マージする API (A) のメソッド定義によってマージ先の API (B) の対応するメソッド定義がオーバーライドされます。たとえば、B200 および 206 レスポンスを返す次のメソッドを宣言しているとします。

GET /a POST /a

A200 および 400 レスポンスを返す次のメソッドを宣言しています。

GET /a

AB にマージされると、作成される API は次のメソッドを呼び出します。

GET /a

これは 200 および 400 レスポンスを返します。また、

POST /a

200 および 206 レスポンスを返します。

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

API (A) によって別の API (B) がオーバーライドされ、作成される API には API (A) の定義が採用されます。API の上書きは、外部の API 定義に、API の完全な定義が含まれているときに役立ちます。このモードでは、インポートされた定義で明確に定義されていない既存の API の項目は削除されます。

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

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

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 定義のペイロードでリクエストをオーバーライドする例を示しています。

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 は最初のオペレーションが成功したかのように、最終的な同じ状態に移行します。