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

OpenAPI ファイルをインポートして既存の 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 を示します。

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

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

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

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

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

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

mode クエリパラメータを指定しないと、マージが想定されます。

注記

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