Private endpoint
Private API
execute-api 인터페이스 VPC 엔드포인트로만 호출되는 REST API입니다. 트래픽은 인터넷을 거치지 않고, Direct Connect로 온프레미스에서도 호출할 수 있습니다.
Amazon API Gateway · 관리형 API 진입점
모든 API 호출을 한 지점에서 인증하고 제어하세요
API Gateway는 REST, HTTP, WebSocket API의 진입점입니다. 요청을 인증하고, 한도를 넘는 트래픽을 제한하고, Lambda나 VPC 안의 서비스로 전달합니다. VPC 안에서만 호출되는 사설 API도 만들 수 있습니다.
Request · prod stageHTTP API
GET /orders/42 HTTP/1.1 Host: api.example.com Authorization: Bearer eyJhbGciOi... Accept: application/json
AuthorizerJWT 검증 통과
Throttling한도 이내
RouteGET /orders/{id}
IntegrationVPC link → ALB
200 OK한도를 넘으면429 Too Many Requests
99.95%
월간 가용성 SLA
10,000
계정·리전당 기본 초당 요청 한도 (상향 요청 가능)
10 MB
REST · HTTP API 최대 페이로드 (REST 응답 스트리밍 제외)
2 h
WebSocket 연결 최대 유지 시간
Why API Gateway
API가 늘어날수록 공통 관문이 필요합니다
서비스마다 인증, 한도 제어, 로깅을 따로 구현하면 정책이 어긋나고 운영 부담이 커집니다. 관문에서 공통 정책을 적용하고, 백엔드는 업무 로직에 집중하게 합니다.
Secure
관문에서 인증
IAM, Lambda authorizer, Cognito와 JWT로 백엔드에 닿기 전에 호출자를 확인합니다.
Control
트래픽 한도
계정, 스테이지와 메서드, 클라이언트 단위로 token bucket 방식의 한도를 적용합니다.
Private
사설 경로
인터페이스 VPC 엔드포인트로 API를 VPC와 온프레미스에만 열고, VPC link로 사설 백엔드에 연결합니다.
API types
REST, HTTP, WebSocket API
HTTP API는 기능을 줄여 더 낮은 가격으로 제공되고, REST API는 사설 엔드포인트, API key, 캐싱, AWS WAF 같은 관리 기능을 갖춥니다. 양방향 실시간 통신에는 WebSocket API를 씁니다.
| 유형 | 통신 모델 | 인증 | 대표 기능 | 맞는 경우 |
|---|---|---|---|---|
| REST API | 요청 · 응답 | IAM, Cognito user pool, Lambda authorizer, resource policy | Edge-optimized · Regional · Private 엔드포인트, API key와 usage plan, 캐싱, AWS WAF, 요청 검증, canary 배포, 응답 스트리밍 | 사설 API, 클라이언트별 한도, 세밀한 요청 변환이 필요한 경우 |
| HTTP API | 요청 · 응답 | IAM, JWT authorizer (Cognito 포함), Lambda authorizer | Regional 엔드포인트, 자동 배포, AWS Cloud Map 사설 통합 | Lambda나 HTTP 백엔드 앞의 단순한 프록시 API |
| WebSocket API | 양방향 지속 연결 | IAM, Lambda authorizer ($connect 라우트) | $connect · $disconnect · $default 라우트, route selection expression, @connections로 서버 푸시 | 채팅, 알림, 실시간 대시보드 |
Authorization
호출자를 확인하는 세 가지 방법
호출자가 AWS 자격 증명을 가진 워크로드인지, 사용자 토큰을 가진 앱인지에 따라 고릅니다.
IAMSigV4
IAM 권한
호출자가 SigV4로 서명한 요청을 IAM 정책으로 판단합니다. REST API는 resource policy로 출발지 VPC, VPC 엔드포인트, 계정을 함께 제한할 수 있습니다.
SigV4IAM policyResource policyaws:SourceVpce
LambdaCustom
Lambda authorizer
헤더나 쿼리 문자열의 토큰을 Lambda 함수가 검사해 허용 여부를 돌려줍니다. 사내 인증 체계나 REST API의 JWT 검증에 씁니다.
TokenRequest parametersREST · HTTP · WebSocket
JWTOIDC
Cognito · JWT authorizer
REST API는 Cognito user pool authorizer를, HTTP API는 JWT authorizer를 씁니다. HTTP API의 JWT authorizer는 Cognito를 비롯한 OIDC 발급자의 토큰을 검증합니다.
Cognito user poolJWT issuerAudienceScopesFeatures
주요 기능
Private domain
Private custom domain
사설 API에 사내 도메인 이름을 붙이고 ACM 인증서로 관리합니다. AWS RAM으로 다른 계정에 공유하고, 소비 계정은 VPC 엔드포인트와 연결해 씁니다.
Throttling
단계별 한도
AWS 리전, 계정, 스테이지와 메서드, 클라이언트 순으로 rate와 burst 한도를 둡니다. 한도를 넘는 요청은 429로 응답합니다.
API management
Usage plan · API key
REST API에서 API key로 클라이언트를 식별하고, 클라이언트별 요청 한도와 기간별 사용량을 정합니다.
Custom domain
사용자 지정 도메인 · mTLS
api.example.com 같은 도메인에 여러 API와 스테이지를 매핑합니다. REST와 HTTP API 모두 mutual TLS로 클라이언트 인증서를 검증할 수 있습니다. REST API는 헤더 기반 routing rule로 요청을 API와 스테이지에 나누고, 백엔드 통합에도 ACM 인증서로 mTLS를 겁니다.
Private integration
VPC link
REST와 HTTP API 모두 VPC link v2로 사설 서브넷의 ALB에 직접 연결하고, NLB 연결도 지원합니다. HTTP API는 AWS Cloud Map에 등록된 서비스로도 보낼 수 있습니다.
Streaming
REST API 응답 스트리밍
Lambda, HTTP 프록시, 사설 통합의 응답을 생성되는 대로 클라이언트에 흘려보냅니다. 첫 바이트가 빨라지고, 통합 타임아웃은 최대 15분, 10 MB를 넘는 응답도 보낼 수 있습니다.
Developer portal
API Gateway Portals
계정의 API를 찾아 문서를 생성하고, PortalProduct로 묶어 사내외 개발자에게 공개하는 관리형 개발자 포털입니다. 접근 제어와 CloudWatch RUM 기반 사용 분석을 제공합니다.
AI agents
MCP proxy
기존 REST API를 Amazon Bedrock AgentCore Gateway와 연결해 MCP 호환 엔드포인트로 노출합니다. 애플리케이션을 바꾸지 않고 AI 에이전트가 API를 도구로 찾아 호출합니다.
Integration types
요청을 백엔드로 넘기는 방식
REST API의 통합 유형입니다. 프록시 유형은 요청과 응답을 그대로 넘기고, 비프록시 유형은 매핑으로 형식을 바꿉니다.
AWS_PROXYLambda 프록시
요청 전체를 Lambda 함수에 넘기는, Lambda 호출에 권장되는 방식입니다.
HTTP_PROXYHTTP 프록시
요청과 응답을 HTTP 엔드포인트와 그대로 주고받습니다. VPC link와 함께 사설 백엔드에 씁니다.
AWS · HTTP매핑 통합
AWS 서비스 액션이나 HTTP 엔드포인트를 호출하며, 통합 요청과 응답의 매핑을 직접 정합니다.
MOCKMock
백엔드를 호출하지 않고 API Gateway가 응답합니다. 테스트와 병행 개발에 씁니다.
Reference architecture
VPC와 온프레미스에만 열린 사설 API
execute-api 인터페이스 엔드포인트를 통해서만 사설 REST API를 호출하고, resource policy로 허용할 VPC 엔드포인트를 지정합니다. 온프레미스 클라이언트는 Direct Connect로 들어와 Resolver inbound 엔드포인트로 이름을 해석합니다.
좁은 화면에서는 다이어그램을 좌우로 밀어서 보세요.
Getting started
사설 API를 여는 순서
- STEP 1
엔드포인트 생성
소비자 VPC에 execute-api 인터페이스 엔드포인트를 만들고 보안 그룹에 443을 허용합니다.
- STEP 2
Private API 생성
엔드포인트 유형을 Private로 골라 REST API를 만듭니다.
- STEP 3
Resource policy
aws:SourceVpce 조건으로 허용할 VPC 엔드포인트를 지정합니다.
- STEP 4
통합 · 배포
메서드에 Lambda나 VPC link 통합을 붙이고 스테이지에 배포합니다.
- STEP 5
호출 확인
VPC 안에서 호출해 보고, 온프레미스는 Resolver inbound 엔드포인트를 거쳐 이름을 해석합니다.
Pricing
비용 항목
API Gateway에는 최소 요금이나 약정이 없고, 받은 API 호출 수와 WebSocket 메시지·연결 시간, 나가는 데이터 전송량으로 비용이 정해집니다. 프리 티어 적용 방식은 계정 가입 시기에 따라 다릅니다.
| 과금 항목 | 과금 기준 | 참고 |
|---|---|---|
| REST API 호출 | 수신한 API 호출 100만 건당, 사용량 구간별 단가 | 프리 티어 대상 계정은 월 100만 건까지 무료입니다. 응답 스트리밍은 응답 10 MB마다 요청 1건으로 셉니다. |
| HTTP API 호출 | 수신한 API 호출 100만 건당 | REST API보다 기능을 줄인 대신 단가가 낮습니다. 프리 티어 대상 계정은 월 100만 건까지 무료입니다. |
| WebSocket API | 주고받은 메시지 100만 건당(32 KB 단위 계량)과 연결 시간(분) | ping·pong 같은 제어 프레임은 계량하지 않습니다. |
| API 캐시 | REST API 스테이지 캐시의 선택한 크기별 시간 요금 | 캐시를 켠 스테이지에만 붙습니다. |
| Portal | Portal당 월 요금(PortalProduct 10개 포함), 추가 PortalProduct당 월 요금 | 월 중 사용 기간에 비례해 청구합니다. |
| 데이터 전송 | 외부로 나가는 데이터 GB당, EC2 데이터 전송 요금 적용 | Private API에는 AWS에서 나가는 데이터 전송(DTO) 요금이 없습니다. |
| Private API 엔드포인트 | execute-api 인터페이스 VPC 엔드포인트의 AZ당 시간 요금과 처리 데이터 GB당 | AWS PrivateLink에서 과금합니다. |
| 연관 서비스 | Lambda 호출, CloudWatch Logs, AWS WAF | 각 서비스에서 따로 과금합니다. |
요금 단가는 리전과 사용량에 따라 다릅니다. 최신 단가는 API Gateway 요금 페이지에서 확인하세요.
Next step
우리 API에 맞는 관문 구성을 함께 정해 보세요
호출 주체, 공개 범위, 예상 트래픽, 백엔드 위치를 정리해 오시면 API 유형과 인증, 네트워크 경로를 함께 검토합니다.