Claude Code e AWS API Gateway: HTTP API com SAM, CORS, logs, autenticação e limites

API Gateway é a porta de entrada da sua API

AWS API Gateway é a camada que recebe chamadas públicas e reúne autenticação, limites, logs e integração com o backend. O navegador, aplicativo móvel, sistema parceiro ou job interno chama uma URL. API Gateway identifica a rota, decide se a chamada pode passar, grava os logs e entrega a requisição para Lambda, um endpoint HTTP ou outro serviço AWS.

Essa definição evita um erro comum com Claude Code. Quando o prompt diz apenas “crie uma API”, a resposta pode gerar uma Lambda que funciona em demonstração, mas sem CORS correto, sem authorizer, sem access logs, sem throttling e sem uma escolha consciente entre HTTP API e REST API. O problema aparece na primeira integração real com frontend ou no primeiro incidente em produção.

Este guia usa a documentação oficial da AWS e cria um exemplo com AWS SAM. A meta é ter uma API simples, copiável e revisável, com pontos de controle que Claude Code consegue verificar.

REST API, HTTP API ou WebSocket API

API Gateway aparece principalmente em três formatos: REST API, HTTP API e WebSocket API. A AWS descreve o serviço como uma forma de criar, publicar e gerenciar APIs que conectam clientes a Lambda, endpoints HTTP e serviços AWS.

Tipo	Melhor uso	Regra prática
HTTP API	APIs JSON para SPA, mobile e Lambda	Comece aqui quando precisar de baixo custo, baixa latência, JWT, CORS, logs e rotas simples
REST API	Gerenciamento avançado de API	Use quando precisar de API keys, usage plans, validação de request, WAF, endpoint privado ou limite por cliente
WebSocket API	Comunicação bidirecional	Use para chat, notificações, progresso em tempo real ou eventos enviados pelo servidor

Na comparação oficial, REST API oferece mais recursos e HTTP API é mais enxuta. Por isso, para formulário, webhook ou API Lambda simples, HTTP API costuma ser suficiente. Quando a monetização, parceiros ou clientes diferentes exigem chaves e planos, REST API ganha força.

Referências oficiais:

• Amazon API Gateway concepts
• Choose between REST APIs and HTTP APIs
• WebSocket APIs
• AWS SAM AWS::Serverless::HttpApi

Casos de uso que mudam o desenho

O primeiro é integração com Lambda. API Gateway expõe a URL pública e Lambda executa a regra de negócio. Isso vale para contato, reserva, webhook de SaaS e pequenas APIs internas.

O segundo é CORS. Se o frontend está em https://example.com e a API em um domínio execute-api, o navegador trata como origem diferente. A documentação da AWS explica que HTTP API pode responder ao preflight OPTIONS quando CORS está configurado. Também informa que, com CORS configurado na API, headers CORS retornados pelo backend podem ser ignorados. Logo, CORS precisa ser desenhado em API Gateway.

O terceiro é autenticação. JWT authorizer funciona bem para usuários finais com Cognito ou OIDC. IAM authorization funciona para workloads AWS com SigV4 e permissão execute-api. Lambda authorizer fica para regras próprias, como base legada, contrato por parceiro ou autorização muito específica.

O quarto é operação. Access logs no CloudWatch devem incluir requestId, routeKey, status, IP e horário. Throttling pode devolver 429 Too Many Requests, mas a AWS trata esses valores como proteção de esforço razoável, não como única barreira. Combine com limites em Lambda, banco e clientes.

Exemplo AWS SAM para copiar

Crie template.yaml.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Claude Code Lab HTTP API sample with CORS, logs, throttling, and Lambda proxy

Parameters:
  StageName:
    Type: String
    Default: Prod
  AllowedOrigin:
    Type: String
    Default: https://example.com

Globals:
  Function:
    Runtime: nodejs20.x
    Architectures:
      - arm64
    Timeout: 10
    MemorySize: 256

Resources:
  ApiAccessLogs:
    Type: AWS::Logs::LogGroup
    Properties:
      RetentionInDays: 14

  PublicHttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      CorsConfiguration:
        AllowOrigins:
          - !Ref AllowedOrigin
        AllowHeaders:
          - authorization
          - content-type
          - x-request-id
        AllowMethods:
          - GET
          - POST
          - OPTIONS
        MaxAge: 300
      AccessLogSettings:
        DestinationArn: !GetAtt ApiAccessLogs.Arn
        Format: '{"requestId":"$context.requestId","routeKey":"$context.routeKey","status":"$context.status","ip":"$context.identity.sourceIp","requestTime":"$context.requestTime","responseLength":"$context.responseLength"}'
      DefaultRouteSettings:
        ThrottlingBurstLimit: 20
        ThrottlingRateLimit: 10
      RouteSettings:
        "POST /contacts":
          ThrottlingBurstLimit: 5
          ThrottlingRateLimit: 2
      FailOnWarnings: true

  HealthFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handler.health
      Events:
        Health:
          Type: HttpApi
          Properties:
            ApiId: !Ref PublicHttpApi
            Path: /health
            Method: GET
            PayloadFormatVersion: "2.0"

  ContactFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handler.contact
      Events:
        Contact:
          Type: HttpApi
          Properties:
            ApiId: !Ref PublicHttpApi
            Path: /contacts
            Method: POST
            PayloadFormatVersion: "2.0"
            TimeoutInMillis: 10000

Outputs:
  ApiUrl:
    Description: Invoke URL
    Value: !Sub "https://${PublicHttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/"

Crie package.json e src/handler.js.

{
  "type": "module",
  "scripts": {
    "check": "node --check src/handler.js"
  }
}

const json = (statusCode, body) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body)
});

export const health = async () => json(200, {
  ok: true,
  service: "claude-code-api-gateway",
  checkedAt: new Date().toISOString()
});

export const contact = async (event) => {
  let payload;
  try {
    payload = JSON.parse(event.body ?? "{}");
  } catch {
    return json(400, { message: "Request body must be valid JSON." });
  }

  const name = String(payload.name ?? "").trim();
  const email = String(payload.email ?? "").trim();
  if (!name || !email.includes("@")) {
    return json(422, { message: "name and a valid email are required." });
  }

  return json(202, {
    message: "accepted",
    requestId: event.requestContext?.requestId,
    received: { name, email }
  });
};

Execute:

npm run check
sam build
sam deploy --guided \
  --stack-name clc-api-gateway-sample \
  --parameter-overrides AllowedOrigin=https://example.com

Prompt de revisão para Claude Code

Revise este template AWS SAM antes de produção.
Procure rotas públicas, CORS amplo demais, falta de JWT/IAM/Lambda authorizer,
logs sem requestId ou routeKey, throttling fraco, respostas Lambda inseguras
e requisitos que indiquem REST API em vez de HTTP API.
Retorne mudanças concretas no template.

Falhas comuns

A primeira falha é deixar CORS apenas na Lambda. Com HTTP API, revise CORS no API Gateway.

A segunda é adiar logs. Muitos 403, 404 e 429 acontecem antes de Lambda.

A terceira é achar que throttling resolve tudo. Também limite Lambda, banco, fila e retries.

A quarta é escolher o tipo de API por hábito. HTTP API é ótima para muitos casos, mas REST API continua importante para API keys, usage plans, WAF e endpoints privados.

Leia também Claude Code AWS Lambda, Claude Code AWS CloudWatch e Claude Code AWS IAM. A página de treinamento reúne checklists para aplicar isso em equipe.

O que Masa testou

Masa testou o fluxo separando desenho, template, Lambda e revisão. Claude Code foi mais útil ao apontar limites mais rígidos em POST /contacts, logs com requestId e routeKey, e rotas públicas marcadas como estado temporário. Começar pelo API Gateway reduziu ruído na implementação da Lambda.