Respostas do gateway para APIs REST no API Gateway

Uma resposta do gateway é identificada por um tipo de resposta definido pelo API Gateway. Essa resposta consiste em um código de status HTTP, um conjunto de cabeçalhos adicionais que são especificados por mapeamentos de parâmetros e uma carga que é gerada por um modelo de mapeamento não VTL.

Na API REST do API Gateway, uma resposta de gateway é representada por GatewayResponse. No OpenAPI, uma instância de GatewayResponse é descrita pela extensão x-amazon-apigateway-gateway-responses.gatewayResponse.

Para permitir uma resposta de gateway, você configura uma resposta de gateway para um tipo de resposta com suporte em nível de API. Sempre que o API Gateway retorna uma resposta desse tipo, os mapeamentos de cabeçalho e os modelos de mapeamento de carga útil definidos na resposta de gateway são aplicados para retornar os resultados mapeados ao autor da chamada da API.

Na seção a seguir, mostramos como configurar respostas de gateway usando o console do API Gateway e a API REST do API Gateway.

Configurar respostas do gateway para personalizar respostas de erro

Se o API Gateway falhar ao processar uma solicitação de entrada, ele retornará ao cliente uma resposta de erro sem encaminhar essa solicitação ao backend de integração. Por padrão, a resposta de erro contém uma breve mensagem de erro descritiva. Por exemplo, se você tentar chamar uma operação em um recurso de API indefinido, receberá uma resposta de erro com a mensagem { "message": "Missing Authentication Token" }. Se você não tem experiência com o API Gateway, talvez ache difícil compreender o que exatamente deu errado.

Para algumas das respostas de erro, o API Gateway permite personalização pelos desenvolvedores de APIs, de modo a retornar as respostas em diferentes formatos. Para o exemplo Missing Authentication Token, você pode adicionar uma dica à carga de resposta original com a causa possível, como neste exemplo: {"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}.

Quando a API faz a intermediação entre um intercâmbio externo e a Nuvem AWS, você usa modelos de mapeamento VTL para a solicitação de integração ou a resposta de integração para mapear a carga útil de um formato para outro. No entanto, os modelos de mapeamento VTL funcionam apenas para solicitações válidas com respostas bem-sucedidas.

Para solicitações inválidas, o API Gateway ignora completamente a integração e retorna uma resposta de erro. É necessário usar a personalização para renderizar as respostas de erro em um formato compatível com intercâmbio. Aqui, a personalização é renderizada em um modelo de mapeamento não VTL que oferece suporte apenas substituições de variáveis simples.

Generalizando a resposta de erro gerada pelo API Gateway para todas as respostas geradas pelo API Gateway, nós as chamamos de respostas de gateway. Isso distingue as respostas geradas pelo API Gateway das respostas de integração. Um modelo de mapeamento de resposta de gateway pode acessar valores de variáveis $context e valores de propriedades $stageVariables, bem como parâmetros de solicitação de método, no formato method.request.param-position.param-name.

Para obter mais informações sobre variáveis $context, consulte Variáveis $context para modelos de dados, autorizadores, modelos de mapeamento e registro de acesso em logs do CloudWatch. Para obter mais informações sobre o $stageVariables, consulte $stageVariables. Para obter mais informações sobre parâmetros de solicitação de método, consulte Variáveis $input.