Importación de un archivo de OpenAPI para actualizar una definición de la API existente
Puede importar las definiciones de la API únicamente para actualizar una API existente, sin cambiar la configuración del punto de enlace, así como las etapas y las variables de etapa o referencias a las claves de API.
La operación de importar para actualizar puede producirse de dos modos: combinación o sobreescritura.
Cuando una API (A) se combina con otra (B), la API resultante conserva las definiciones de A y B si las dos API no comparten definiciones contradictorias. Si surge un conflicto, las definiciones de método de la combinación de la API (A) invalida las definiciones de método correspondientes de la API combinada (B). Suponga, por ejemplo, que B ha declarado los siguientes métodos para devolver las respuestas 200 y 206:
GET /a POST /a
y A declara el siguiente método para devolver las respuestas 200 y 400:
GET /a
Cuando A se combina con B, la API resultante presenta los siguientes métodos:
GET /a
que devuelve las respuestas 200 y 400, y
POST /a
que devuelve las respuestas 200 y 206.
Combinar una API es útil cuando ha descompuesto sus definiciones de API externas en varias partes más pequeñas y solo desea aplicar los cambios de una de esas partes a la vez. Esto podría ocurrir, por ejemplo, si varios equipos son responsables de diferentes partes de una API y han realizado cambios disponibles en diferentes partes. En este modo, los elementos de la API existente que no están específicamente definidos en la definición importada se dejan tal como están.
Cuando una API (A) sobrescribe otra API (B), la API resultante adopta las definiciones de la API sobrescrita (A). Sobrescribir una API es útil cuando una definición de API externa contiene la definición completa de una API. En este modo, los elementos de una API existente que no están específicamente definidos en la definición importada se eliminan.
Para combinar una API, envíe una solicitud PUT a https://apigateway.. El valor del parámetro de ruta <region>.amazonaws.com/restapis/<restapi_id>?mode=mergerestapi_id especifica la API con la que debe combinarse la definición de API proporcionada.
El siguiente fragmento de código muestra un ejemplo de la solicitud PUT para combinar una definición de la API de OpenAPI en JSON, como la carga, con la API ya especificada en API Gateway.
PUT /restapis/<restapi_id>?mode=merge Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ...An OpenAPI API definition in JSON
La operación de actualización por combinación toma dos definiciones de API completas y las combina. Para un cambio pequeño e incremental, puede usar la operación resource update.
Para sobrescribir una API, envíe una solicitud PUT a https://apigateway.. El parámetro de ruta <region>.amazonaws.com/restapis/<restapi_id>?mode=overwriterestapi_id especifica la API que se sobrescribirá con las definiciones de API proporcionadas.
El siguiente fragmento de código muestra un ejemplo de una solicitud de sobrescritura con la carga de una definición de OpenAPI con formato JSON:
PUT /restapis/<restapi_id>?mode=overwrite Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ...An OpenAPI API definition in JSON
Cuando no se especifica el parámetro de consulta mode, se supone que se trata de una combinación.
nota
Las operaciones PUT son idempotentes, pero no atómicas. Eso significa que si se produce un error del sistema durante el procesamiento, la API puede acabar en mal estado. Sin embargo, si se repite la operación de forma exitosa, la API acaba en el mismo estado final que tendría si la primera operación se hubiera realizado con éxito.
