Claude Code et AWS API Gateway : HTTP API avec SAM, CORS, logs, authentification et limites

API Gateway est la porte d’entrée de votre API

AWS API Gateway est la couche qui reçoit les requêtes publiques et regroupe authentification, limitation, journalisation et connexion au backend. Le navigateur, l’application mobile ou le système partenaire appelle une URL. API Gateway identifie la route, vérifie si la requête peut passer, écrit les logs et l’envoie vers Lambda, un endpoint HTTP ou un service AWS.

Cette définition change la façon d’utiliser Claude Code. Si le prompt dit seulement « crée une API », Claude Code peut générer une Lambda fonctionnelle tout en oubliant les questions de production : CORS, authorizer, logs d’accès, throttling, noms de stages et choix entre REST API et HTTP API. Le code répond en local, mais l’équipe découvre les problèmes quand le frontend est bloqué ou quand un incident n’est pas traçable.

Ce guide reprend le sujet depuis les sources officielles AWS et fournit un exemple AWS SAM que l’on peut copier. L’objectif est de produire une API Gateway exploitable, pas uniquement une démo.

Choisir REST API, HTTP API ou WebSocket API

API Gateway propose surtout trois formes : REST API, HTTP API et WebSocket API. AWS le décrit comme un service de création et gestion d’API reliant des clients à Lambda, des endpoints HTTP ou d’autres services AWS.

Type	Usage adapté	Décision pratique
HTTP API	API JSON pour SPA, mobile et Lambda	Choix par défaut pour coût faible, faible latence, JWT, CORS, logs et routes simples
REST API	Gestion API riche	À choisir pour API keys, usage plans, validation de requêtes, WAF, endpoint privé ou quotas par client
WebSocket API	Communication bidirectionnelle	Pour chat, notifications, progression en direct ou événements envoyés par le serveur

La documentation AWS compare clairement les deux mondes : REST API offre plus de fonctionnalités, HTTP API a un périmètre plus réduit et plus économique. Une équipe qui expose une API Lambda simple devrait souvent commencer par HTTP API. Si les besoins de gouvernance apparaissent, REST API devient plus pertinente.

Sources officielles:

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

Quatre cas d’usage à clarifier

Le premier cas est l’intégration Lambda. Formulaire de contact, réservation, webhook SaaS ou petite API interne : API Gateway expose la route publique et Lambda garde la logique métier.

Le deuxième cas est CORS. Quand le frontend vit sur https://example.com et l’API sur un domaine execute-api, le navigateur applique des règles d’origine. AWS indique que la configuration CORS d’une HTTP API peut répondre aux requêtes OPTIONS de prévalidation. AWS précise aussi que, si CORS est configuré sur l’API, API Gateway peut ignorer les en-têtes CORS renvoyés par le backend. Il faut donc concevoir CORS dans API Gateway, pas seulement dans Lambda.

Le troisième cas est l’authentification. JWT authorizer convient aux utilisateurs finaux avec Cognito ou un fournisseur OIDC. IAM authorization convient aux workloads AWS signés avec SigV4 et autorisés via execute-api. Lambda authorizer est utile pour des règles propriétaires : base de comptes historique, contrats partenaires, filtrage IP ou droits complexes.

Le quatrième cas est l’exploitation. Les access logs CloudWatch doivent contenir requestId, routeKey, status, IP et heure. Le throttling peut renvoyer 429 Too Many Requests, mais AWS le présente comme un objectif de protection plutôt qu’une garantie absolue. Il faut donc aussi protéger Lambda, la base de données et les appels externes.

Exemple AWS SAM copiable

Créez 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}/"

Ajoutez package.json et 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 }
  });
};

Déployez:

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

Prompt de revue Claude Code

Relis ce template AWS SAM avant production.
Vérifie les routes publiques, CORS trop large, absence de JWT/IAM/Lambda authorizer,
logs sans requestId ni routeKey, throttling trop faible, erreurs Lambda dangereuses
et besoins qui imposeraient REST API au lieu de HTTP API.
Donne des changements concrets.

Ce prompt demande une revue de risques. C’est le bon angle pour API Gateway, car une route publique oubliée ou des logs incomplets coûtent souvent plus cher qu’une petite erreur de syntaxe.

Pièges courants

Premier piège : gérer CORS uniquement dans Lambda. Avec HTTP API, la configuration CORS doit être relue au niveau API Gateway.

Deuxième piège : repousser les access logs. Beaucoup de 403, 404 ou 429 arrivent avant Lambda.

Troisième piège : croire que le throttling suffit. Il faut aussi limiter Lambda, base de données et clients.

Quatrième piège : choisir le produit par habitude. HTTP API est souvent suffisant, mais REST API reste nécessaire pour API keys, usage plans, WAF et endpoints privés.

Pour continuer, lisez Claude Code AWS Lambda, Claude Code AWS CloudWatch et Claude Code AWS IAM. La page formation regroupe aussi les checklists pratiques.

Ce que Masa a testé

Masa a testé ce flux en séparant conception, template, Lambda et revue. Les meilleurs retours concernaient les limites plus strictes sur POST /contacts, la présence de requestId et routeKey dans les logs, et le fait de marquer les routes publiques comme temporaires. Commencer par API Gateway a rendu la Lambda plus simple.