Claude Code und AWS API Gateway: HTTP API mit SAM, CORS, Logs, Auth und Throttling

API Gateway ist die Eingangsschicht Ihrer API

AWS API Gateway ist die Schicht, die öffentliche API-Aufrufe annimmt und Authentifizierung, Begrenzung, Logging und Backend-Anbindung bündelt. Ein Browser, eine mobile App, ein Partnersystem oder ein interner Job ruft eine URL auf. API Gateway erkennt die Route, prüft den Zugriff, schreibt Access Logs und leitet an Lambda, einen HTTP-Endpunkt oder einen AWS-Service weiter.

Für Claude Code ist diese Definition wichtig. Wenn der Prompt nur „baue eine API“ lautet, entsteht oft eine Lambda, die in der Demo funktioniert, aber CORS, Authorizer, Access Logs, Throttling, Stage-Namen und die Produktwahl zwischen HTTP API und REST API nicht sauber behandelt. Das rächt sich, sobald ein Frontend blockiert wird oder ein Fehler nicht nachvollziehbar ist.

Dieser Artikel nutzt AWS-Dokumentation als Grundlage und zeigt ein AWS-SAM-Beispiel, das kopiert und anschließend von Claude Code überprüft werden kann. Ziel ist keine Spielzeug-API, sondern eine kleine, betreibbare Eingangsschicht.

REST API, HTTP API oder WebSocket API wählen

API Gateway wird meist in drei Formen genutzt: REST API, HTTP API und WebSocket API. AWS beschreibt den Dienst als Möglichkeit, APIs zu erstellen und zu verwalten, die Clients mit Lambda, HTTP-Backends oder AWS-Services verbinden.

Typ	Geeignet für	Praktische Entscheidung
HTTP API	JSON APIs für SPAs, mobile Apps und Lambda	Startpunkt bei niedrigen Kosten, geringer Latenz, JWT, CORS, Logs und einfachen Routen
REST API	Umfangreiches API-Management	Für API Keys, Usage Plans, Request Validation, WAF, private Endpunkte oder Mandantenlimits
WebSocket API	Bidirektionale Kommunikation	Für Chat, Benachrichtigungen, Live-Fortschritt oder Server-Push

Die offizielle AWS-Vergleichsseite zeigt: REST API hat mehr Funktionen, HTTP API ist schlanker und günstiger. Ein Kontaktformular, Webhook oder Lambda-Backend startet meist mit HTTP API. Wenn Kundentarife, API Keys oder WAF-Pflichten auftauchen, sollte REST API geprüft werden.

Offizielle Quellen:

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

Vier Use Cases vor dem Code klären

Der erste Use Case ist Lambda-Integration. API Gateway stellt die öffentliche URL bereit, Lambda verarbeitet die Geschäftslogik. Das passt für Kontaktformulare, Buchungen, SaaS-Webhooks und kleine interne APIs.

Der zweite Use Case ist CORS. Liegt das Frontend auf https://example.com und die API auf einer execute-api-Domain, behandelt der Browser beide als verschiedene Origins. AWS dokumentiert, dass HTTP API CORS-Konfiguration Preflight-OPTIONS-Anfragen beantworten kann. Wenn CORS auf API-Ebene gesetzt ist, können CORS-Header aus der Backend-Integration ignoriert werden. CORS gehört deshalb in die API-Gateway-Konfiguration.

Der dritte Use Case ist Authentifizierung. JWT Authorizer passen für Endnutzer mit Cognito oder OIDC. IAM Authorization passt für AWS-Workloads, die mit SigV4 signieren und execute-api-Rechte besitzen. Lambda Authorizer sind sinnvoll, wenn Legacy-Benutzer, Partnerverträge, IP-Regeln oder komplexe Berechtigungen geprüft werden müssen.

Der vierte Use Case ist Betrieb. CloudWatch Access Logs sollten requestId, routeKey, Status, IP und Zeit enthalten. Throttling kann 429 Too Many Requests zurückgeben. AWS beschreibt Throttles und Quotas aber als Schutzwerte, nicht als perfekte harte Grenze. Lambda-Concurrency, Datenbanklimits und Client-Backoff bleiben wichtig.

Kopierbares AWS-SAM-Beispiel

Erstellen Sie 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}/"

Ergänzen Sie package.json und 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 }
  });
};

Ausführen:

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

Claude-Code-Review-Prompt

Überprüfe dieses AWS-SAM-Template vor Produktion.
Suche öffentliche Routen, zu breites CORS, fehlende JWT/IAM/Lambda Authorizer,
Access Logs ohne requestId oder routeKey, zu schwaches Throttling,
unsichere Lambda-Fehlerantworten und Anforderungen, die REST API statt HTTP API verlangen.
Gib konkrete Template-Änderungen zurück.

Dieser Prompt verlangt eine Risikoprüfung statt zusätzlichen Code. Genau das passt zu API Gateway: Eine versehentlich öffentliche Route oder fehlende Logs sind im Betrieb teurer als eine kleine Lambda-Formatfrage.

Häufige Fallen

Erste Falle: CORS nur in Lambda setzen. Bei HTTP API muss die CORS-Konfiguration in API Gateway geprüft werden.

Zweite Falle: Access Logs später aktivieren. Viele 403, 404 und 429 passieren vor Lambda.

Dritte Falle: Throttling als perfekte Grenze verstehen. Es braucht zusätzlich Limits in Lambda, Datenbank und Clients.

Vierte Falle: API-Typ nach Gewohnheit wählen. HTTP API ist oft richtig, REST API bleibt aber wichtig für API Keys, Usage Plans, WAF und private Endpunkte.

Weitere passende Artikel sind Claude Code AWS Lambda, Claude Code AWS CloudWatch und Claude Code AWS IAM. Die Training-Seite sammelt Checklisten für Teams.

Was Masa getestet hat

Masa hat den Ablauf in Design, Template, Lambda und Review getrennt. Nützlich waren Hinweise auf strengere Limits für POST /contacts, Logs mit requestId und routeKey sowie das Markieren öffentlicher Routen als temporären Zustand. Der Start bei API Gateway machte die Lambda-Implementierung deutlich ruhiger.