Integrações: Lambda, HTTP e simulação

Todo método do API Gateway precisa de uma integração com um backend — o sistema que processa a requisição e retorna uma resposta. O API Gateway oferece suporte a cinco tipos de integração: Lambda Proxy, Lambda Custom, HTTP Proxy, HTTP Custom e Mock. As APIs HTTP oferecem suporte somente a Lambda Proxy e HTTP Proxy. As APIs REST são compatíveis com os cinco tipos. A escolha da integração correta determina quanto controle você terá sobre a transformação da requisição e da resposta.

Com a integração Lambda Proxy, o API Gateway transmite toda a requisição HTTP ao Lambda como um objeto de evento estruturado, incluindo cabeçalhos, strings de consulta, parâmetros de caminho, corpo e contexto. Sua função do Lambda é responsável por retornar um objeto de resposta devidamente formatado, com statusCode, headers e body. Este é o padrão mais simples e comum — não são necessários modelos de mapeamento, e o Lambda controla toda a resposta.

Com a integração Lambda Non-Proxy (personalizada), o API Gateway usa modelos de mapeamento (Apache Velocity Template Language, VTL) para transformar a requisição antes de enviá-la ao Lambda e transforma a resposta do Lambda antes de devolvê-la ao cliente. Sua função do Lambda recebe uma carga útil personalizada e limpa, não o evento bruto do API Gateway. Isso separa as preocupações de transporte da lógica de negócios, mas exige a manutenção de modelos VTL. Use a integração personalizada quando quiser uma separação rigorosa entre o contrato da API e o contrato do backend.

A integração HTTP Proxy encaminha requisições diretamente para um endpoint HTTP externo (que pode ser uma instância do EC2, um ALB, um servidor local ou qualquer URL pública) sem transformação. O API Gateway repassa a requisição e retorna a resposta do backend ao cliente. Essa opção é ideal para migrar backends REST existentes para o API Gateway e adicionar limitação de taxa, monitoramento e chaves de API sem alterar o código do backend. Oferece suporte a backends HTTPS com verificação de certificado.

A integração HTTP Custom também encaminha requisições para um endpoint HTTP externo, mas usa modelos de mapeamento para transformar tanto a requisição enviada ao backend quanto a resposta recebida. Isso é útil quando a interface do API Gateway e a API do backend têm contratos diferentes — você pode converter uma chamada de API REST em SOAP legado ou em um formato personalizado e transformar a resposta do backend novamente em uma estrutura JSON limpa para o cliente. Isso adiciona complexidade, mas oferece o maior controle para integrações legadas.

A integração com AWS Service conecta o API Gateway diretamente aos serviços da AWS, sem um intermediário do Lambda. Por exemplo, você pode configurar um endpoint POST que grava diretamente uma mensagem no SQS, publica no SNS ou inicia uma execução do Step Functions. Isso reduz a latência e elimina os custos de funções do Lambda em operações simples de roteamento. A integração exige a configuração de uma função do IAM e modelos de mapeamento para formatar corretamente a chamada à API da AWS.

Integração Mock configura o API Gateway para retornar uma resposta predefinida sem chamar nenhum back-end. Você define a resposta no modelo de mapeamento da resposta da integração. As integrações Mock são perfeitas para: desenvolver a API antes de o back-end estar pronto (as equipes de front-end podem começar imediatamente), testar configurações da API, retornar cabeçalhos CORS padrão ou fornecer um substituto para parceiros terceirizados durante o desenvolvimento. Os endpoints Mock também podem ser usados para bloquear versões obsoletas da API, retornando 410 Gone.

CORS (compartilhamento de recursos entre origens) deve ser habilitado quando um cliente de navegador em um domínio chama sua API em outro domínio. A API HTTP oferece configuração de CORS com um clique; a API REST exige que você crie um método OPTIONS com uma integração Mock que retorne os cabeçalhos CORS necessários (Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers). A integração de proxy do Lambda também exige que sua função Lambda retorne cabeçalhos CORS na resposta.

A API REST oferece validação de solicitações: o API Gateway pode validar se os parâmetros obrigatórios da string de consulta, os cabeçalhos e o esquema do corpo da solicitação estão presentes e formatados corretamente antes de invocar o back-end. Isso reduz invocações desnecessárias do Lambda causadas por solicitações malformadas e retorna automaticamente erros 400 padronizados. Defina um modelo de solicitação usando o esquema JSON e associe-o ao método para habilitar a validação do corpo. A validação de solicitações não está disponível na API HTTP.

O API Gateway tem um tempo limite de integração padrão de 29 segundos para a API REST e a API HTTP (máximo para a API REST e fixo para o proxy da API HTTP). Se o back-end levar mais de 29 segundos, o API Gateway retornará um erro 504 Gateway Timeout. Isso significa que as funções Lambda invocadas de forma síncrona pelo API Gateway devem ser concluídas em até 29 segundos, embora o próprio Lambda ofereça suporte a tempos limite de 15 minutos. Para operações demoradas, use um padrão assíncrono: o API Gateway aciona o Lambda, que inicia uma tarefa assíncrona e retorna imediatamente um ID da tarefa.

Guia de decisão para tipos de integração: Proxy do Lambda: mais comum, mais simples e com controle total da solicitação no Lambda; Lambda personalizado: quando você precisa transformar a solicitação ou a resposta na camada do gateway; Proxy HTTP: para back-ends HTTP existentes e cenários de migração; HTTP personalizado: para traduzir formatos de APIs legadas; AWS Service: para eliminar o Lambda em roteamentos simples para SQS/SNS/DynamoDB; Mock: para substitutos de desenvolvimento e solicitações preliminares de CORS. No exame SAA-C03, os padrões Proxy do Lambda e Proxy HTTP são os mais cobrados.

Teste sua compreensão dos conceitos de AWS Solutions Architect (SAA-C03) desta lição.

Nesta lição, você aprendeu que a integração Proxy do Lambda passa a solicitação completa ao Lambda, que controla a resposta — é a integração mais simples e comum; o Proxy HTTP encaminha solicitações para back-ends HTTP existentes, adicionando recursos do API Gateway sem alterar o back-end; e a integração Mock retorna respostas predefinidas para o desenvolvimento e os testes do front-end, sem nenhuma infraestrutura de back-end. A seguir, exploraremos a autorização do API Gateway com IAM, autorizadores do Lambda e Cognito.