# OpenAPI ファイルをインポートして既存の API 定義を更新する
<a name="api-gateway-import-api-update"></a>

 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=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 定義を使用し、それらをマージします。小さい増分変更の場合は、[リソースの更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)オペレーションを使用できます。

 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 は最初のオペレーションが成功した場合と同じ最終状態になります。