OpenAPI ファイルをインポートして既存の API 定義を更新する
API 定義をインポートできるのは、エンドポイント設定、ステージおよびステージ変数、または API キーへの参照を変更せずに既存の API を更新する場合のみです。
インポートから更新への操作は、マージまたは上書きという 2 つのモードで行うことができます。
API (A
) が別の API (B
) にマージされると、作成された API では、2 つの API で矛盾する定義が共有されていない限り、A
と B
の両方の定義が保持されます。矛盾が発生した場合、マージする API (A
) のメソッド定義によってマージ先の API (B
) の対応するメソッド定義がオーバーライドされます。たとえば、B
が 200
および 206
レスポンスを返す次のメソッドを宣言しているとします。
GET /a POST /a
A
は 200
および 400
レスポンスを返す次のメソッドを宣言しています。
GET /a
A
が B
にマージされると、作成される 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=mergerestapi_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=overwriterestapi_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 は最初のオペレーションが成功した場合と同じ最終状態になります。