[AWS] API Gateway: REST/HTTP/WebSocket API 관리

aws-api-gateway, API Gateway, AWS API Gateway, REST API Gateway, HTTP API Gateway, WebSocket API

정의

AWS API Gateway 는 REST / HTTP / WebSocket API 를 관리하는 완전관리형 서비스. 인증, 스로틀링, 캐싱, 요청/응답 변환, 로깅을 단일 서비스로 제공. Lambda 와 결합해 서버리스 백엔드의 진입점이 된다.

API 타입 비교

항목	REST API	HTTP API	WebSocket API
출시	2015	2019	2018
통신 방식	요청/응답 (무상태)	요청/응답 (무상태)	양방향 상태 유지
비용	$3.50/million	$1.00/million	$1.00/million (+ 연결 시간)
지연시간	높음	낮음	-
JWT authorizer	Lambda 만	내장	Lambda 만
WAF 통합	가능	X	X
Request validator	있음	X	X
Usage Plan / API Key	있음	X	X
Response 캐싱	있음	X	-
Private endpoint	있음	X	-
ALB / Cloud Map 프라이빗 통합	X	있음	-
NLB 프라이빗 통합	있음	있음	-
자동 배포	X	있음	-
카나리 배포	있음	X	-
X-Ray 추적	있음	X	-
Mock 통합	있음	X	-
요청 본문 변환 (VTL)	있음	X	-

엔드포인트 타입 (REST API)

REST API 는 어디에서 노출될지 3가지 유형 중 선택.

타입	특징	Use Case
Edge-optimized	CloudFront 엣지 경유, 전세계 지연 최소화 (기본값)	지리적으로 분산된 클라이언트
Regional	특정 리전에서 직접 제공 (엣지 우회)	같은 리전 클라이언트, 자체 CloudFront 구성
Private	VPC 내부에서만 (인터페이스 엔드포인트)	내부 전용 API, 규정 준수

AWS 서비스 직접 통합 (Lambda 생략 패턴)

Lambda 없이 SQS / SNS / DynamoDB / Step Functions / Kinesis 직접 호출. 비용/지연/관리 최소화.

예: 요청 -> SQS 큐 (Lambda 없음)

integration:
  type: AWS
  integrationHttpMethod: POST
  uri: "arn:aws:apigateway:us-east-1:sqs:path/123456789/my-queue"
  credentials: "arn:aws:iam::123:role/apigw-sqs-role"
  requestParameters:
    "integration.request.header.Content-Type": "'application/x-www-form-urlencoded'"
  requestTemplates:
    "application/json": "Action=SendMessage&MessageBody=$util.urlEncode($input.body)"

언제 유리:

• API 는 단순히 요청을 수집만 하고, 실제 처리는 비동기
• 트래픽 급증 시 SQS 로 버퍼링
• Lambda 를 없애 콜드 스타트 회피 + 비용 절감

아키텍처: Lambda 프록시 통합

flowchart LR
    Client["클라이언트"] -->|"HTTPS (TLS)"| APIGW["API Gateway"]
    APIGW -->|"JWT / Lambda 인증"| Auth["Authorizer"]
    Auth -->|"allow"| APIGW
    APIGW -->|"Lambda Proxy 요청"| Lambda["Lambda"]
    Lambda -->|"응답"| APIGW
    APIGW -->|"HTTP 응답"| Client

    APIGW -.->|"실패 시"| APIGW

Lambda proxy 통합: API Gateway 가 원본 요청을 그대로 Lambda 에 전달 (path, headers, body, queryStringParameters 포함). Lambda 는 statusCode, headers, body 를 포함한 JSON 을 반환.

통합 타입

Lambda Proxy

{
  "httpMethod": "POST",
  "path": "/users",
  "headers": { "Authorization": "Bearer ..." },
  "queryStringParameters": { "page": "1" },
  "body": "{\"name\": \"alice\"}"
}

Lambda 응답:

{
  "statusCode": 201,
  "headers": { "Content-Type": "application/json" },
  "body": "{\"id\": \"u123\"}"
}

HTTP Proxy

외부 URL 로 요청 그대로 포워딩. 변환 없음.

# 통합 설정
integration:
  type: HTTP_PROXY
  uri: "http://internal-alb.example.com/{proxy}"
  httpMethod: ANY

VPC Link

프라이빗 VPC 내 ALB/NLB 와 연결. 인터넷 노출 없이 내부 서비스 연결.

flowchart LR
    APIGW["API Gateway"] -->|"VPC Link"| VL["VPC Link"]
    VL --> NLB["NLB (private)"]
    NLB --> SVC["내부 서비스"]

AWS 서비스 직접 통합

Lambda 없이 DynamoDB, SQS, S3 등 직접 호출.

integration:
  type: AWS
  uri: "arn:aws:apigateway:us-east-1:dynamodb:action/PutItem"
  credentials: "arn:aws:iam::123:role/apigw-dynamo-role"

인증/인가

Lambda Authorizer (커스텀)

def handler(event, context):
    token = event['authorizationToken']
    # JWT 검증 또는 DB 조회
    effect = "Allow" if valid(token) else "Deny"
    return {
        "principalId": "user123",
        "policyDocument": {
            "Version": "2012-10-17",
            "Statement": [{
                "Action": "execute-api:Invoke",
                "Effect": effect,
                "Resource": event['methodArn']
            }]
        },
        "context": { "userId": "u123" }   # Lambda 로 전달 가능
    }

캐싱: Lambda Authorizer 결과를 TTL 동안 캐시. 기본 300초. 비용 절감 + 지연시간 단축.

JWT Authorizer (HTTP API 전용)

authorizer:
  type: JWT
  jwtConfiguration:
    issuer: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx"
    audience: ["client-id-1"]
  identitySource: "$request.header.Authorization"

Cognito, Auth0, Okta 등 OIDC 호환 IdP 와 바로 연동. Lambda 불필요.

IAM + SigV4

AWS SDK / CLI 로 서명된 요청. 내부 서비스 간 통신에 적합.

스로틀링 설정

flowchart TD
    Req["요청"] --> AccLim["계정 레벨<br/>10,000 rps / 5,000 burst"]
    AccLim --> APILim["API/Stage 레벨<br/>사용자 지정"]
    APILim --> MethodLim["메서드 레벨<br/>사용자 지정"]
    MethodLim --> UsagePlan["Usage Plan<br/>API Key 별 quota"]

레벨	기본값	변경
계정 전체	10,000 rps / burst 5,000	Support 티켓으로 증가
Stage/API	계정 한도 공유	콘솔/API 로 설정
메서드	Stage 한도 공유	각 메서드별 오버라이드
Usage Plan	일/월 quota, rps	API Key 단위

429 Too Many Requests 반환 시 Retry-After 헤더 제공.

스테이지 관리

prod (v1)   →  stage variables: LOG_LEVEL=WARN
staging     →  stage variables: LOG_LEVEL=DEBUG
dev         →  stage variables: LOG_LEVEL=DEBUG

• Stage Variable: 스테이지별 환경 변수. Lambda alias 로 활용 가능.
• Canary deployment: 스테이지에서 일부 트래픽만 새 버전으로.
• Deployment: Stage 에 변경사항 반영 (명시적 배포 필요).

캐싱 (REST API)

# 캐시 활성화
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations \
    op=replace,path=/cacheClusterEnabled,value=true \
    op=replace,path=/cacheClusterSize,value=0.5

캐시 크기	비용/시간
0.5 GB	$0.020
1.6 GB	$0.038
6.1 GB	$0.200
13.5 GB	$0.250

요청/응답 변환 (REST API)

Velocity Template Language (VTL) 로 매핑:

#set($inputRoot = $input.path('$'))
{
  "userId": "$inputRoot.id",
  "email": "$inputRoot.contact.email"
}

HTTP API 는 변환 불가 (Lambda 내부에서 처리).

사용 패턴

BFF (Backend for Frontend)

flowchart LR
    Web["Web 클라이언트"] --> GWAY["API Gateway<br/>BFF"]
    Mobile["Mobile 클라이언트"] --> GWAY
    GWAY --> UserSvc["User Service<br/>Lambda"]
    GWAY --> OrderSvc["Order Service<br/>Lambda"]
    GWAY --> PaySvc["Payment Service<br/>Lambda"]

Microservice Gateway

각 마이크로서비스에 별도 API Gateway 대신 단일 진입점 제공.

이벤트 수신 (SNS/SQS 연결)

Client → API Gateway → SQS → Lambda consumer

비동기 처리 패턴. 즉시 202 Accepted 반환, 실제 처리는 SQS 로.

비용 구조

항목	REST API	HTTP API
첫 3억 요청/월	$3.50/million	$1.00/million
3억 초과	$1.51/million	$0.90/million
캐싱	별도 시간당 요금	없음
데이터 전송	AWS 표준	AWS 표준

비용 절감 팁:

• HTTP API 우선 사용 (70% 저렴)
• 캐싱으로 Lambda 호출 감소
• REST API 의 Usage Plan 으로 초과 사용 방지

대안 비교

옵션	특성	적합한 경우
API Gateway HTTP	낮은 비용, JWT 내장	신규 서버리스 API
API Gateway REST	풍부한 기능, WAF, 캐싱	레거시 마이그레이션, API Key 관리
**[[aws-alb-nlb	ALB]]**	고성능, 저렴, L7 LB
AppSync	GraphQL 특화, 실시간	GraphQL API, 모바일
CloudFront + Functions	초저지연 엣지	간단 API 변환

함정

관련 위키

• aws-lambda - 주 통합 대상
• aws-lambda-cold-start - 콜드 스타트 문제
• aws-alb-nlb - 대안 L7 로드밸런서
• aws-vpc - 프라이빗 엔드포인트
• aws-iam - SigV4 인증
• aws-waf - 요청 필터링
• aws-cloudwatch - API 모니터링
• aws-sqs - 비동기 패턴 연결