Configurar uma resposta de método no API Gateway

Uma resposta de método de API encapsula a saída de uma solicitação de método de API que será recebida pelo cliente. Os dados de saída incluem um código de status HTTP, alguns cabeçalhos e possivelmente um corpo.

Com integrações não proxy, os parâmetros de resposta especificados e o corpo podem ser mapeados dos dados de resposta de integração associados ou podem receber certos valores estáticos de acordo com os mapeamentos. Esses mapeamentos são especificados na resposta de integração. O mapeamento pode ser uma transformação idêntica que passe pela resposta de integração no estado em que se encontra.

Com uma integração de proxy, o API Gateway passa a resposta de backend para a resposta de método automaticamente. Não há necessidade de configurar a resposta de método de API. No entanto, com a integração de proxy do Lambda, a função do Lambda deve retornar um resultado desse formato de saída para o API Gateway mapear com êxito a resposta de integração a uma resposta de método.

Programaticamente, a configuração da resposta de método equivale à criação de um recurso MethodResponse do API Gateway e à definição das propriedades de statusCode, responseParameters e responseModels.

Ao definir os códigos de status de um método de API, você deve escolher um como o padrão para lidar com qualquer resposta de integração de um código de status imprevisto. É razoável definir 500 como padrão, pois isso equivale à geração de respostas não mapeadas de outra forma como um erro no servidor. Por motivos educacionais, o console do API Gateway define a resposta 200 como padrão. No entanto, você pode redefini-la como a resposta 500.

Para configurar uma resposta de método, você deve ter criado a solicitação de método.

Configurar o código de status de resposta de método

O código de status de uma resposta de método define um tipo de resposta. Por exemplo, as respostas 200, 400 e 500 indicam respostas bem-sucedidas de erros no servidor e no cliente, respectivamente.

Para configurar um código de status de resposta de método, defina a propriedade statusCode como um código de status HTTP. O seguinte comando da AWS CLI cria uma resposta de método 200.

aws apigateway put-method-response \
       --region us-west-2  \
       --rest-api-id vaz7da96z6 \ 
       --resource-id 6sxz2j \
       --http-method GET \
       --status-code 200  

Configurar parâmetros da resposta de método

Os parâmetros da resposta de método definem quais cabeçalhos o cliente recebe em resposta à solicitação de método associada. Os parâmetros de resposta também especificam um destino para o qual o API Gateway mapeia um parâmetro de resposta de integração de acordo com os mapeamentos prescritos na resposta de integração do método de API.

Para configurar os parâmetros de resposta de método, adicione ao mapa responseParameters de pares de chave-valor MethodResponse do formato "{parameter-name}":"{boolean}". O comando da CLI a seguir mostra um exemplo de configuração do cabeçalho my-header.

aws apigateway put-method-response \
        --region us-west-2 \
        --rest-api-id vaz7da96z6 \
        --resource-id 6sxz2j \
        --http-method GET \
        --status-code 200  \
        --response-parameters method.response.header.my-header=false

Configurar modelos de resposta de método

Um modelo de resposta de método define um formato do corpo de resposta de método. Antes de configurar o modelo de resposta, você deve primeiro criar o modelo no API Gateway. Para fazer isso, você pode chamar o comando create-model. O exemplo a seguir mostra como criar um modelo PetStorePet para descrever o corpo da resposta para a solicitação do método GET /pets/{petId}.

aws apigateway create-model \
    --region us-west-2 \
    --rest-api-id vaz7da96z6 \
    --content-type application/json \
    --name PetStorePet \
    --schema '{ \
                  "$schema": "http://json-schema.org/draft-04/schema#", \
                  "title": "PetStorePet", \
                  "type": "object", \
                  "properties": { \
                    "id": { "type": "number" }, \
                    "type": { "type": "string" }, \
                    "price": { "type": "number" } \
                  } \
              }'

O resultado é criado como um recurso Model do API Gateway.

Para configurar os modelos de resposta de método a fim de definir o formato de carga útil, adicione o par de chave-valor "application/json":"PetStorePet" ao mapa requestModels do recurso MethodResponse. O seguinte comando da AWS CLI de put-method-response mostra como isso é feito:

aws apigateway put-method-response \
        --region us-west-2 \
        --rest-api-id vaz7da96z6 \
        --resource-id 6sxz2j \
        --http-method GET \
        --status-code 200  \
        --response-parameters method.response.header.my-header=false \
        --response-models '{"application/json":"PetStorePet"}'    

A configuração de um modelo de resposta de método é necessária quando você gera um SDK fortemente tipado para a API. Ela garante que a saída seja gerada em uma classe apropriada em Java ou Objective-C. Em outros casos, a definição de um modelo é opcional.