Claude Code와 AWS API Gateway: SAM으로 HTTP API, CORS, 로그, 인증, 제한 만들기

API Gateway는 공개 API의 입구다

AWS API Gateway는 외부에 공개하는 API의 입구 계층입니다. 브라우저, 모바일 앱, 파트너 시스템, 내부 배치 작업이 하나의 URL을 호출하면 API Gateway가 route를 판단하고, 인증 여부를 확인하고, access log를 남기고, 요청을 Lambda, HTTP 백엔드, AWS 서비스로 전달합니다.

Claude Code를 쓸 때 이 정의가 중요합니다. 프롬프트에 “API 만들어 줘”라고만 쓰면 Lambda 코드는 동작할 수 있습니다. 하지만 CORS, JWT 또는 IAM 인증, access log, throttling, stage 이름, HTTP API와 REST API 선택은 빠질 수 있습니다. 데모는 통과하지만 실제 프런트엔드가 붙는 순간 CORS에서 막히거나, 장애 때 requestId를 찾지 못하는 일이 생깁니다.

이 글은 AWS 공식 문서를 기준으로 API Gateway를 다시 정리하고, AWS SAM으로 복사해 실행할 수 있는 HTTP API 예제를 만듭니다. 목표는 “돌아가는 API”가 아니라 Claude Code로 리뷰할 수 있는 운영 가능한 입구를 만드는 것입니다.

REST API, HTTP API, WebSocket API 중 무엇을 고를까

API Gateway는 보통 REST API, HTTP API, WebSocket API 세 가지로 나뉩니다. AWS는 API Gateway를 클라이언트와 Lambda, HTTP endpoint, AWS 서비스를 연결하는 API 생성 및 관리 서비스로 설명합니다.

종류	적합한 용도	실무 판단
HTTP API	SPA, 모바일, Lambda 기반 JSON API	낮은 비용, 낮은 지연, JWT, CORS, 로그, 단순 route가 필요하면 먼저 선택
REST API	고급 API 관리	API key, usage plan, request validation, WAF, private endpoint, 고객별 제한이 필요하면 선택
WebSocket API	양방향 통신	채팅, 알림, 실시간 진행률, 서버 push가 필요하면 선택

AWS 비교 문서에 따르면 REST API는 기능이 더 많고, HTTP API는 기능 범위를 줄여 비용과 지연을 낮춘 제품입니다. 문의 폼, 예약, webhook, 간단한 Lambda API는 HTTP API로 충분한 경우가 많습니다. API key나 고객별 usage plan이 필요해지면 REST API를 검토합니다.

공식 참고:

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

코드 전에 정해야 할 네 가지 유스케이스

첫째는 Lambda 연동입니다. API Gateway는 공개 URL과 route를 담당하고, Lambda는 비즈니스 로직을 담당합니다. 문의 폼, 예약 폼, SaaS webhook, 작은 내부 API에 잘 맞습니다.

둘째는 CORS입니다. 프런트엔드가 https://example.com에 있고 API가 execute-api 도메인에 있으면 브라우저는 서로 다른 origin으로 봅니다. AWS 문서는 HTTP API의 CORS 설정이 preflight OPTIONS 요청에 응답할 수 있다고 설명합니다. 또한 API에 CORS가 설정되어 있으면 백엔드 통합에서 반환한 CORS header가 무시될 수 있다고 설명합니다. 그래서 CORS는 Lambda에 흩어 쓰기보다 API Gateway에서 설계해야 합니다.

셋째는 인증입니다. JWT authorizer는 Cognito나 OIDC 토큰을 쓰는 사용자 API에 맞습니다. IAM authorization은 SigV4로 서명하고 execute-api 권한을 가진 AWS workload 호출에 맞습니다. Lambda authorizer는 기존 회원 DB, 파트너 계약, IP 제한, 복잡한 권한처럼 자체 규칙이 필요할 때 사용합니다.

넷째는 로그와 제한입니다. CloudWatch access log에는 requestId, routeKey, status, IP, 시간이 들어가야 조사하기 쉽습니다. Throttling은 초과 요청에 429 Too Many Requests를 반환할 수 있지만, AWS는 이를 절대적인 벽이 아니라 보호 목표로 설명합니다. Lambda 동시 실행 수, DB 제한, 클라이언트 backoff도 함께 설계합니다.

복사해서 쓰는 AWS SAM 예제

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

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

실행합니다.

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

Claude Code 리뷰 프롬프트

이 AWS SAM template를 production 전에 리뷰해 주세요.
공개 route, 너무 넓은 CORS, JWT/IAM/Lambda authorizer 누락,
requestId 또는 routeKey 없는 access log, 약한 throttling,
안전하지 않은 Lambda 오류 응답, HTTP API보다 REST API가 필요한 요구사항을 찾으세요.
구체적인 template 수정안을 주세요.

이 프롬프트는 코드를 더 만들라는 요청이 아니라 운영 리스크를 찾으라는 요청입니다. API Gateway는 입구이므로, 작은 기능보다 잘못 열린 문과 부족한 로그가 더 큰 문제가 됩니다.

흔한 실패

첫째, CORS를 Lambda에만 쓰는 것입니다. HTTP API에서는 API Gateway의 CORS 설정을 기준으로 리뷰해야 합니다.

둘째, access log를 나중으로 미루는 것입니다. 많은 403, 404, 429는 Lambda에 도달하기 전에 발생합니다.

셋째, throttling을 완벽한 상한으로 믿는 것입니다. Lambda, DB, queue, client retry도 같이 설계해야 합니다.

넷째, 습관으로 API 타입을 고르는 것입니다. HTTP API는 많은 단순 API에 좋지만, API key, usage plan, WAF, private endpoint는 REST API가 필요할 수 있습니다.

이어 읽을 글은 Claude Code AWS Lambda, Claude Code AWS CloudWatch, Claude Code AWS IAM입니다. 팀용 체크리스트는 training 페이지에 모았습니다.

Masa가 손元에서 확인한 결과

Masa는 설계, template, Lambda, 리뷰를 나누어 이 흐름을 시험했습니다. Claude Code가 가장 도움 된 부분은 POST /contacts가 /health보다 강한 제한을 가져야 한다는 점, access log에 requestId와 routeKey가 있어야 한다는 점, 공개 route를 임시 상태로 표시해야 한다는 점이었습니다. API Gateway부터 시작하니 Lambda 구현도 더 단순해졌습니다.