Importar um arquivo do OpenAPI para atualizar uma definição de API existente
Você pode importar as definições de APIs apenas para atualizar uma API existente, sem alterar sua configuração de endpoint, bem como os estágios e suas variáveis ou referências a chaves de APIs.
A operação de importação para atualização pode ocorrer em dois modos: mesclagem ou substituição.
Quando uma API (A) é mesclada com outra (B), a API resultante retém as definições de A e B, se as duas APIs não compartilharem definições conflitantes. Em caso de conflito, as definições de método da API de mesclagem (A) substituem as definições de método correspondentes da API mesclada (B). Por exemplo, suponha que B tenha declarado os seguintes métodos para retornar as respostas 200 e 206:
GET /a POST /a
e que A declare o seguinte método para retornar as respostas 200 e 400:
GET /a
Quando A é mesclada com B, a API resultante produz os seguintes métodos:
GET /a
que retorna 200 e 400 respostas e
POST /a
que retorna 200 e 206 respostas.
A mesclagem de uma API é útil quando você decompôs suas definições de API externas em várias partes menores e apenas deseja aplicar as alterações de uma dessas partes de cada vez. Por exemplo, isso pode ocorrer se várias equipes são responsáveis por diferentes partes de uma API e têm alterações disponíveis em ritmos diferentes. Nesse modo, os itens da API existente que não estiverem especificamente indicados na definição importada serão ignorados.
Quando uma API (A) substitui outra API (B), a API resultante assume as definições da API de substituição (A). A substituição de uma API é útil quando uma definição de API externa contém a definição completa de uma API. Nesse modo, os itens de uma API existente que não estiverem especificamente indicados na definição importada serão excluídos.
Para mesclar uma API, envie uma solicitação PUT para https://apigateway.. O valor do parâmetro do caminho <region>.amazonaws.com/restapis/<restapi_id>?mode=mergerestapi_id especifica a API com a qual a definição de API fornecida será mesclada.
O seguinte trecho de código mostra um exemplo da solicitação PUT para mesclar uma definição de API do OpenAPI em JSON, como a carga útil, com a API especificada já no 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
A operação de atualização se mesclagem usa duas definições de API completas e as mescla em uma só. Para uma alteração pequena e incremental, você pode usar a operação de atualização de recursos.
Para substituir uma API, envie uma solicitação PUT para https://apigateway.. O parâmetro de caminho <region>.amazonaws.com/restapis/<restapi_id>?mode=overwriterestapi_id especifica a API que será substituída pelas definições de API fornecidas.
O seguinte trecho de código mostra um exemplo de uma solicitação de substituição com a carga de uma definição do OpenAPI formatada em JSON:
PUT /restapis/<restapi_id>?mode=overwrite Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ...An OpenAPI API definition in JSON
Quando o parâmetro de consulta mode não é especificado, supõe-se uma mesclagem.
nota
As operações PUT são idempotentes, mas não atômicas. Isso significa que, se um erro de sistema ocorrer no meio do processamento, a API poderá terminar em mau estado. No entanto, repetir a operação com êxito coloca a API no mesmo estado final, como se a primeira operação tivesse sido bem-sucedida.
