Day 1 - API Gateway REST API: 요청이 백엔드에 도달하기까지의 전체 경로

Amazon API Gateway가 처음 등장한 2015년, 서버리스 API를 만드는 방법은 EC2에 Flask나 Express를 올리거나, Elastic Beanstalk를 쓰는 것이었다. API Gateway는 "Lambda 함수를 HTTP 엔드포인트로 노출하는 관리형 서비스"라는 역할로 시작했지만, 시간이 지나며 인증·캐싱·트래픽 제어·모니터링이 붙은 완전한 API 관리 플랫폼으로 성장했다.

오늘은 REST API의 내부 구조를 완전히 해부한다. 클라이언트가 HTTP 요청을 보내는 순간부터 Lambda가 호출되고 응답이 돌아오기까지, 그 경로의 모든 계층이 무엇을 하는지 이해하면 시험의 API Gateway 문제를 풀 때 근거가 선다.

API Gateway가 필요한 이유: Lambda Function URL과의 비교

Lambda에는 2022년부터 Function URL이 있다. API Gateway 없이도 Lambda 함수에 직접 HTTPS 엔드포인트를 붙일 수 있다. 그런데 왜 API Gateway를 쓰는가?

선택 기준: 단일 Lambda + 단순 HTTP 노출 → Function URL. 복잡한 라우팅·인증·캐싱·사용량 제한 필요 → REST API. 비용이 민감하고 단순한 Lambda/HTTP 프록시 → HTTP API.

REST API의 계층 구조: 리소스, 메서드, 통합, 스테이지

REST API는 트리 구조다.

API (MyShopAPI)
  └── 리소스 /products
        ├── GET  → 통합(Lambda: ListProducts)
        │           ├── 통합 요청 (요청 변환)
        │           └── 통합 응답 (응답 변환)
        ├── POST → 통합(Lambda: CreateProduct)
        └── /products/{productId}
              ├── GET    → 통합(Lambda: GetProduct)
              ├── PUT    → 통합(Lambda: UpdateProduct)
              └── DELETE → 통합(Lambda: DeleteProduct)

리소스(Resource): URL 경로. {} 중괄호로 경로 파라미터 선언. 메서드(Method): GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. 통합(Integration): 메서드가 호출하는 백엔드. Lambda, HTTP, AWS 서비스, Mock. 스테이지(Stage): 배포 환경. dev, staging, prod. 배포(Deployment): API 변경사항의 스냅샷. 스테이지에 연결해야 반영됨.

⚠️ 함정: API를 변경한 후 반드시 배포를 생성하고 스테이지에 연결해야 변경이 적용된다. 콘솔에서 "저장"만 하고 배포를 빠뜨리면 클라이언트는 여전히 이전 버전의 API를 보게 된다.

요청이 이동하는 경로: 6단계 완전 분석

클라이언트 요청 (HTTPS)
        │
        ▼
[1. 엔드포인트 수신]
   Edge-Optimized: CloudFront PoP에서 TLS termination
   Regional: 리전 API Gateway 직접
   Private: VPC Interface Endpoint 경유
        │
        ▼
[2. 메서드 요청 (Method Request)]
   - 인증 (IAM SigV4, Lambda Authorizer, Cognito)
   - 경로 파라미터, 헤더, 쿼리스트링 검증
   - 요청 모델(JSON Schema) 검증
   실패 시 → 400/401/403 즉시 반환
        │
        ▼
[3. 통합 요청 (Integration Request)]
   - VTL 매핑 템플릿으로 요청 변환
   - Lambda / HTTP 엔드포인트 / AWS 서비스 호출
        │
        ▼
[4. 백엔드 처리]
   - Lambda 실행
   - HTTP 엔드포인트 응답
   - DynamoDB 응답 등
        │
        ▼
[5. 통합 응답 (Integration Response)]
   - 백엔드 응답 → VTL 매핑 템플릿으로 변환
   - Lambda Proxy면 변환 없이 그대로
        │
        ▼
[6. 메서드 응답 (Method Response)]
   - HTTP 상태 코드, 헤더, 응답 모델 설정
   - 클라이언트에게 최종 응답 전달

이 6단계를 이해하면 API Gateway 트러블슈팅이 쉬워진다.

• 401/403이 나오면 → [2] 인증 계층 확인
• 400이 나오면 → [2] 요청 검증 실패 (파라미터 / 모델)
• 502 Bad Gateway → [4] 백엔드 오류 (Lambda 에러 or 포맷 문제)
• 504 Timeout → [4] 백엔드 타임아웃 (Lambda 30초 제한 초과)

세 가지 엔드포인트 유형과 선택 기준

Edge-Optimized: CloudFront의 600+ PoP에서 TLS를 종료하고 백본망으로 요청을 전달. 글로벌 사용자가 많은 공개 API에 적합. 단, 실제 CloudFront 콘솔에는 보이지 않는 AWS 관리형 CloudFront다. 커스텀 CloudFront 설정이 필요하면 Regional + 별도 CloudFront를 사용한다.

Regional: 동일 리전의 클라이언트가 직접 연결. EC2나 Lambda에서 같은 리전 API를 호출할 때 유리. 자체 CloudFront를 붙여 캐싱과 WAF를 추가할 수 있다.

Private: VPC 내부의 Interface Endpoint(PrivateLink)를 통해서만 접근 가능. 인터넷에서 절대 접근 불가. 사내 마이크로서비스 API, 데이터 파이프라인 API에 적합.

⚠️ 함정: Edge-Optimized 커스텀 도메인의 ACM 인증서는 반드시 us-east-1에서 발급해야 한다. 이는 CloudFront가 us-east-1 ACM만 참조하기 때문이다. "도메인이 동작하지 않아요"라는 시나리오에서 인증서를 us-east-1이 아닌 다른 리전에서 발급한 경우가 흔한 원인이다. Regional 엔드포인트는 각 리전의 ACM에서 발급해도 된다.

스테이지와 스테이지 변수: 환경별 라우팅

스테이지는 단순히 "dev/staging/prod"를 구분하는 것 이상이다. 스테이지 변수를 통해 동일한 API 정의로 다른 백엔드에 라우팅할 수 있다.

API 통합 URI:
arn:aws:lambda:ap-northeast-2:123:function:OrderAPI:${stageVariables.lambdaAlias}

dev 스테이지:   lambdaAlias = dev  → OrderAPI:dev  (별칭)
prod 스테이지:  lambdaAlias = prod → OrderAPI:prod (별칭)

스테이지 변수 활용 패턴:

• Lambda 별칭 분기 (일반적인 방식)
• HTTP 통합 URL 분기 (${stageVariables.backendUrl})
• AWS 서비스 ARN 분기

# 스테이지 변수 설정
aws apigateway create-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --variables 'lambdaAlias=prod,backendUrl=https://api.mycompany.com'

스테이지 변수는 API Gateway 레벨의 환경 변수다. Lambda 함수의 환경 변수와는 다른 계층이다. Lambda 환경 변수는 함수 실행 시 코드에 노출되고, 스테이지 변수는 API Gateway가 통합 URI를 구성할 때 치환된다. 두 개를 함께 쓰면 API Gateway → Lambda 통합에서 스테이지별 다른 함수를 호출하고, 각 함수 내부에서는 자체 환경 변수로 추가 설정을 관리하는 구조가 된다.

REST API vs HTTP API vs WebSocket API: 핵심 비교표

시험 시나리오 키워드 → 선택:

• "API 키와 사용량 플랜으로 파트너별 차등 제한" → REST API
• "비용 최소화, 단순 Lambda 프록시" → HTTP API
• "WAF로 SQL 인젝션 방어" → REST API
• "JWT 자동 검증 (Cognito/Auth0/Okta)" → HTTP API (JWT Authorizer 내장)
• "실시간 채팅, 게임, 협업 도구" → WebSocket API
• "X-Ray 분산 추적" → REST API

커스텀 도메인: api.mycompany.com 설정

Route 53 A 레코드 (Alias)
api.mycompany.com → API Gateway Custom Domain
        │
        ▼
API Gateway Custom Domain Name
  + ACM 인증서 (HTTPS TLS)
        │
        ▼ Base Path Mapping
/v1 → REST API "MyAPI" stage "prod"
/v2 → REST API "MyAPI-v2" stage "prod"
/internal → REST API "InternalAPI" stage "prod"

# 커스텀 도메인 생성 (Regional 엔드포인트)
aws apigateway create-domain-name \
  --domain-name api.mycompany.com \
  --endpoint-configuration types=REGIONAL \
  --regional-certificate-arn arn:aws:acm:ap-northeast-2:123:certificate/abc
 
# Base Path Mapping (하나의 도메인으로 여러 API 라우팅)
aws apigateway create-base-path-mapping \
  --domain-name api.mycompany.com \
  --rest-api-id abc123 \
  --stage prod \
  --base-path v1

REST API 내장 카나리 배포

Lambda 별칭의 카나리와는 별도로, REST API 스테이지 자체에 카나리를 활성화할 수 있다.

# 스테이지에 카나리 설정 (새 배포의 10%만 카나리로)
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations \
    'op=replace,path=/canarySettings/percentTraffic,value=10' \
    'op=replace,path=/canarySettings/deploymentId,value=new-deploy-id'
 
# 카나리 승격 (100%로)
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=replace,path=/canarySettings/percentTraffic,value=0'

API Gateway 카나리(배포 버전 수준)와 Lambda 별칭 카나리(함수 버전 수준)를 함께 쓰면 두 겹의 안전장치가 생겨 배포 위험을 줄일 수 있다.

OpenAPI(Swagger) Import/Export

API 정의를 코드로 관리하거나 팀 간에 공유할 때 OpenAPI 3.0 형식을 사용한다.

# openapi.yaml
openapi: "3.0.1"
info:
  title: "ProductAPI"
  version: "1.0"
 
paths:
  /products:
    get:
      summary: "상품 목록 조회"
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri: "arn:aws:apigateway:ap-northeast-2:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-northeast-2:123:function:ListProducts/invocations"
        payloadFormatVersion: "1.0"
      responses:
        "200":
          description: "성공"

# OpenAPI 정의로 API import
aws apigateway import-rest-api \
  --body file://openapi.yaml \
  --region ap-northeast-2
 
# 기존 API 업데이트 (merge 모드)
aws apigateway put-rest-api \
  --rest-api-id abc123 \
  --mode merge \
  --body file://openapi.yaml

가격 모델

데이터 전송: 첫 10TB/월은 $0.09/GB, 이후 단계별 할인.

HTTP API는 REST API보다 요금이 낮아 웹훅 수신처럼 짧은 요청이 많은 워크로드에 유리하다. 다만 API 키와 사용량 플랜이 HTTP API에는 없으므로, 사용량 추적이 필요한 API는 REST API를 쓴다.

정리

API Gateway REST API는 HTTP 요청을 받아 인증하고, 검증하고, 변환하고, 백엔드를 호출하고, 응답을 변환해 돌려주는 6단계 파이프라인이다. 엔드포인트 유형은 트래픽 경로를 결정하고, 스테이지는 환경별 배포 단위이며, 스테이지 변수는 하나의 API 정의로 여러 환경에 유연하게 연결하는 메커니즘이다. REST, HTTP, WebSocket 세 가지 API 유형은 기능과 비용에서 명확한 트레이드오프가 있으며, 요구 사항에 맞게 선택하면 된다.

다음 글에서는 API Gateway 통합의 핵심인 Lambda Proxy 통합, VTL 매핑 템플릿, AWS 서비스 직접 통합을 파고든다.