Como montar seu primeiro backend com API Gateway e Lambda

Um roteiro direto do console da AWS até uma HTTP API funcionando, com os tropeços mais comuns de quem faz isso pela primeira vez.

Nota da redação: este artigo foi verificado contra a documentação oficial da AWS (página 'Getting started' do API Gateway), e o tutorial em si (passos, código, tempos, comparação entre tipos de API e limpeza de recursos) bate com a fonte. Porém, quatro detalhes complementares não constam no texto-fonte usado na checagem e não puderam ser confirmados: o detalhamento das permissões IAM necessárias, a lista de recursos avançados da REST API (API keys, request validation, cache por estágio), a exigência de lambda:InvokeFunction em integrações via CLI/IaC, e os tipos específicos de autorizador (IAM, JWT, Lambda authorizer). São informações plausíveis e consistentes com o ecossistema AWS, mas o leitor deve confirmar esses pontos específicos na documentação antes de tomar decisões de produção com base neles.

Se você já ouviu falar de Lambda e API Gateway mas nunca colocou os dois pra conversar, este é o caminho mais curto que eu conheço: um backend completo, sem servidor para gerenciar, rodando em menos de 20 minutos e dentro do AWS Free Tier. É o roteiro que eu seguiria com quem está começando na nuvem ou estudando para uma certificação AWS, e que também serve de revisão rápida para quem já trabalha com API Gateway no dia a dia.

Vamos construir uma HTTP API que recebe uma requisição GET, aciona uma function Lambda e devolve a resposta dela para o cliente. É o desenho mais simples possível de uma API orientada a eventos: quem publica a requisição é o navegador (ou qualquer client HTTP), quem consome é o Lambda, e quem faz a ponte é o API Gateway.

Pré-requisitos

Antes de abrir o console, confira o que você precisa ter:

• Uma conta AWS ativa, com acesso ao console.
• Um usuário IAM com acesso ao console e permissão para criar functions no Lambda e APIs no API Gateway, conforme pede a documentação oficial. Em produção, restrinja o escopo dessas permissões ao mínimo necessário.
• Um navegador. Não precisa instalar nada localmente: a function roda no runtime gerenciado do console.
• Cerca de 20 minutos, segundo a estimativa da própria documentação da AWS.

Se seu time trabalha com usuários no Brasil, já acostume o olho com a região São Paulo (sa-east-1) em vez do us-east-1 padrão. A documentação oficial usa us-east-2 nos prints, mas a região não muda nenhum passo do exercício.

Passo 1: criar a function Lambda

O console do Lambda já vem com um template pronto para este tipo de exercício, e é nele que a documentação se apoia.

1. Acesse o console do Lambda.
2. Clique em Create function.
3. Em Function name, digite my-function.
4. Deixe o restante no padrão e confirme.

O runtime default do console muda com o tempo; a documentação não fixa uma versão específica, então confira qual aparece selecionada no momento em que você passar por esse passo. O código de exemplo que já vem pronto é este:

export const handler = async (event) => {
  const response = {
    statusCode: 200,
    body: JSON.stringify('Hello from Lambda!'),
  };
  return response;
};

Repare no formato da resposta: statusCode e body são obrigatórios para o API Gateway entender o que fazer com o retorno da function. Se sua function devolver qualquer outra coisa, como um objeto solto, o API Gateway não sabe montar a resposta HTTP e você recebe um erro genérico na integração.

Passo 2: criar a HTTP API

Aqui entra a escolha que mais importa neste tutorial: o tipo de API.

Para este backend, a HTTP API é a escolha certa: ela foi desenhada com o mínimo de recursos justamente para custar menos por requisição, segundo a própria documentação da AWS.

No console do API Gateway:

1. Escolha Build em HTTP API (ou Create API e depois Build se já tiver outras APIs na conta).
2. Em Integrations, clique em Add integration e escolha Lambda.
3. Em Lambda function, digite my-function.
4. Em API name, digite my-http-api.
5. Avance, revise a rota que o console cria automaticamente (ela usa o nome da sua function como path) e revise o stage sugerido.
6. Clique em Create.

Pronto: você tem uma HTTP API com integração Lambda, sem escrever uma linha de infraestrutura como código.

Passo 3: testar a API

Com a API criada, o console mostra a invoke URL na página de detalhes da API. Copie essa URL e acrescente o nome da sua function no final, porque é esse o path da rota criada automaticamente.

A URL completa fica parecida com:

https://abcdef123.execute-api.sa-east-1.amazonaws.com/my-function

Cole no navegador. O navegador dispara um GET, o API Gateway roteia para o Lambda, o Lambda roda e devolve a resposta, e o API Gateway repassa pro navegador. Se tudo deu certo, você vê o texto Hello from Lambda! na tela.

Onde costuma quebrar

Os erros mais comuns nesse exercício não estão no código, estão no caminho:

• URL sem o path da function: a documentação é clara nesse ponto: é preciso completar a invoke URL com o nome da sua function no final, porque é esse o path da rota que o console cria automaticamente. Colar só a invoke URL pura tende a não acionar a rota certa.
• Região errada: preste atenção na região onde você criou a API. O endpoint do API Gateway é específico de cada região, então testar a URL fora do contexto da região onde a API foi criada não funciona como esperado.
• Function renomeada depois da integração: se você mudar o nome da function no Lambda depois de criar a API, vale conferir se a integração no API Gateway ainda aponta pro recurso certo.
• Permissão de invocação: se você montar essa integração via CLI ou infraestrutura como código, em vez do console, não esqueça de configurar a permissão lambda:InvokeFunction para o principal do API Gateway.

O que este exercício não cobre

Isso é o esqueleto, não um backend pronto para produção. A própria documentação lista o que vem depois:

• Outros tipos de integração: endpoints HTTP externos, recursos privados numa VPC (como serviços do Amazon ECS) ou serviços da AWS como Amazon SQS, Step Functions e Kinesis Data Streams.
• Controle de acesso, via autorização IAM, JWT authorizer ou Lambda authorizer.
• Logging, para rastrear cada requisição.
• Throttling, para limitar taxa de requisições por client.
• Domínio customizado, em vez do endpoint padrão execute-api.amazonaws.com.

Para quem trabalha com API Gateway no dia a dia, esse é o ponto onde o exercício de primeiro backend vira projeto de verdade: a escolha do tipo de autorização e o desenho do que acontece quando o Lambda falha, com retry ou dead-letter queue, definem se a API aguenta tráfego real.

Limpeza: não deixe recurso órfão rodando

Mesmo dentro do Free Tier, vale o hábito de limpar o que você cria em exercício. São quatro remoções:

1. No console do API Gateway, selecione a API e escolha Actions e depois Delete.
2. No console do Lambda, selecione a function e escolha Actions e depois Delete.
3. No CloudWatch, abra Log groups, selecione /aws/lambda/my-function e delete.
4. No IAM, abra Roles, selecione a role que o Lambda criou (algo como my-function-role-<id>) e delete.

Esses quatro passos removem a API, a function, o log group e a execution role. Se você pular o log group ou a role, eles ficam parados sem custo direto, mas poluem a conta e dificultam auditoria depois.

Automatizando o que você acabou de fazer manualmente

Tudo isso que passou pelo console dá para descrever em CloudFormation ou AWS SAM, o que vale a pena assim que você sair do modo "só testando" e for repetir o padrão em outro projeto. A documentação da AWS mantém templates de exemplo prontos para essa migração do clique para o código.

Fonte

Documentação do Amazon API Gateway, Getting started (https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started.html)

Fonte: Documentação do Amazon API Gateway — Getting started