Claude Code dan AWS API Gateway: HTTP API dengan SAM, CORS, log, auth, dan throttling

API Gateway adalah pintu masuk API publik

AWS API Gateway adalah lapisan yang menerima request publik dan menggabungkan autentikasi, pembatasan, logging, serta koneksi ke backend. Browser, aplikasi mobile, sistem partner, atau job internal memanggil satu URL. API Gateway menentukan route, mengecek apakah request boleh lewat, menulis access log, lalu meneruskannya ke Lambda, endpoint HTTP, atau layanan AWS lain.

Ini penting saat memakai Claude Code. Jika prompt hanya berbunyi “buatkan API”, Claude Code bisa membuat Lambda yang berjalan, tetapi belum tentu menata CORS, authorizer, access log, throttling, stage, dan pilihan HTTP API atau REST API. Demo berhasil, tetapi produksi sulit dilacak.

Artikel ini memakai dokumentasi resmi AWS sebagai dasar, lalu membuat contoh AWS SAM yang bisa disalin. Fokusnya bukan sekadar API yang hidup, tetapi API yang bisa direview dan dioperasikan.

Memilih REST API, HTTP API, atau WebSocket API

API Gateway umum dipakai dalam tiga bentuk: REST API, HTTP API, dan WebSocket API. AWS menjelaskan API Gateway sebagai layanan untuk membuat dan mengelola API yang menghubungkan client ke Lambda, endpoint HTTP, atau layanan AWS.

Jenis	Cocok untuk	Aturan praktis
HTTP API	API JSON untuk SPA, mobile, dan Lambda	Mulai dari sini bila perlu biaya rendah, latensi rendah, JWT, CORS, log, dan route sederhana
REST API	Manajemen API lengkap	Gunakan untuk API key, usage plan, validasi request, WAF, private endpoint, atau limit per client
WebSocket API	Komunikasi dua arah	Gunakan untuk chat, notifikasi, progres real-time, atau event dari server

Dokumentasi AWS menunjukkan REST API punya fitur lebih banyak, sedangkan HTTP API lebih ringan dan murah. Untuk form kontak, webhook, atau API Lambda sederhana, HTTP API sering cukup. Jika perlu API key, usage plan, atau WAF, REST API perlu dipertimbangkan.

Referensi resmi:

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

Empat use case sebelum menulis kode

Pertama, integrasi Lambda. API Gateway menyediakan URL publik, sedangkan Lambda menjalankan logika bisnis. Ini cocok untuk form kontak, booking, webhook SaaS, dan API internal kecil.

Kedua, CORS. Jika frontend ada di https://example.com dan API memakai domain execute-api, browser melihatnya sebagai origin berbeda. AWS menjelaskan bahwa konfigurasi CORS di HTTP API dapat menjawab preflight OPTIONS. AWS juga menjelaskan bahwa saat CORS dikonfigurasi di API, header CORS dari backend bisa diabaikan. Jadi CORS harus dirancang di API Gateway, bukan hanya di Lambda.

Ketiga, autentikasi. JWT authorizer cocok untuk user dengan Cognito atau OIDC. IAM authorization cocok untuk workload AWS yang memakai tanda tangan SigV4 dan izin execute-api. Lambda authorizer cocok bila ada aturan khusus seperti database lama, kontrak partner, pembatasan IP, atau izin kompleks.

Keempat, operasi. Access log CloudWatch sebaiknya memuat requestId, routeKey, status, IP, dan waktu. Throttling dapat mengembalikan 429 Too Many Requests, tetapi nilainya bukan pelindung absolut. Tetap batasi Lambda, database, dan retry client.

Contoh AWS SAM yang bisa disalin

Buat 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}/"

Tambahkan package.json dan 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 }
  });
};

Jalankan:

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

Prompt review untuk Claude Code

Review template AWS SAM ini sebelum production.
Cari route publik, CORS terlalu luas, JWT/IAM/Lambda authorizer yang belum ada,
access log tanpa requestId atau routeKey, throttling terlalu lemah,
error response Lambda yang tidak aman, dan kebutuhan yang lebih cocok untuk REST API.
Berikan perubahan template yang konkret.

Kesalahan yang sering terjadi

Pertama, menaruh CORS hanya di Lambda. Pada HTTP API, CORS perlu direview di API Gateway.

Kedua, menunda access log. Banyak 403, 404, dan 429 terjadi sebelum Lambda dipanggil.

Ketiga, menganggap throttling sebagai batas sempurna. Tetap gunakan batas Lambda, database, dan retry dengan backoff.

Keempat, memilih tipe API karena kebiasaan. HTTP API cocok untuk banyak API sederhana, tetapi REST API tetap penting untuk API key, usage plan, WAF, dan private endpoint.

Baca juga Claude Code AWS Lambda, Claude Code AWS CloudWatch, dan Claude Code AWS IAM. Materi praktik ada di halaman training.

Hasil yang dicoba Masa

Masa mencoba alur ini dengan memisahkan desain, template, Lambda, dan review. Claude Code paling membantu saat menunjukkan bahwa POST /contacts perlu throttling lebih ketat daripada /health, access log harus punya requestId dan routeKey, dan route publik harus dianggap sementara. Memulai dari API Gateway membuat kode Lambda lebih sederhana.