API Gateway를 운영 경계로 보는 법

기술 실무 설계 시리즈 5/8

API Gateway는 종종 Lambda 앞에 붙이는 프록시처럼 여겨진다.

요청을 받아 Lambda로 넘겨주는 역할 말이다.

하지만 브라우저 기반 운영 콘솔에서는 API Gateway를 단순 프록시로 보면 부족하다.

CORS, 라우팅, 스로틀링, 로그, 인증 확장성, 백엔드 교체 가능성까지 포함한 운영 경계로 보는 편이 더 맞다.

API 앞단에는 정책이 필요하다

프론트엔드가 API를 호출할 때 단순히 백엔드 함수만 있으면 되는 것이 아니다.

운영 중에는 다음 정책이 필요하다.

• 어떤 path를 허용할 것인가
• 어떤 method를 허용할 것인가
• 어떤 origin에서 호출할 수 있는가
• preflight는 어디서 처리할 것인가
• 요청이 너무 많으면 어떻게 제한할 것인가
• 어떤 로그를 남길 것인가
• 나중에 백엔드를 바꿀 수 있는가

이 정책을 모두 애플리케이션 코드에 넣을 수도 있다.

하지만 일부는 Gateway 계층에서 다루는 편이 낫다.

CORS는 설계 요소다

React SPA와 API 도메인이 다르면 CORS가 발생한다.

JSON 요청이나 credentials를 쓰면 preflight도 생긴다.

이때 API Gateway가 있으면 OPTIONS 요청을 Lambda까지 보내지 않고 처리할 수 있다.

Browser OPTIONS
-> API Gateway MOCK response
-> Lambda 호출 없음

이 구조는 비용과 지연을 줄이고, Lambda 코드에서 CORS 분기를 줄인다.

CORS는 에러가 아니라 브라우저 보안 모델이다.

따라서 운영 콘솔에서는 처음부터 설계해야 한다.

path와 method가 운영 단위가 된다

API Gateway를 쓰면 path와 method 단위로 API를 볼 수 있다.

예를 들어:

GET /api/dashboard
POST /api/reports
GET /api/jobs/{jobId}
POST /api/sync

이 구조는 운영상 유용하다.

어떤 endpoint가 있는지 보이고, method별 정책을 둘 수 있으며, 로그와 metric도 path 단위로 볼 수 있다.

Lambda Function URL만 쓰면 path 분기를 코드 안에서만 관리하게 될 수 있다.

작은 API라면 괜찮지만 endpoint가 늘어나면 Gateway의 가시성이 도움이 된다.

스로틀링과 보호

운영 API는 실수로 과도하게 호출될 수 있다.

사용자가 버튼을 반복 클릭할 수도 있고, 자동화 스크립트가 루프를 돌 수도 있다.

API Gateway는 스로틀링이나 usage plan 같은 보호 장치를 둘 수 있다.

이것은 비용 보호이면서 백엔드 보호다.

특히 Lambda 뒤에 RDS가 있다면 요청 폭주가 DB connection 문제로 이어질 수 있다.

Gateway에서 1차 제한을 두는 것은 운영 안전장치가 된다.

로그와 관측성

API Gateway는 요청이 Lambda까지 갔는지 확인하는 경계다.

장애가 났을 때 다음을 구분할 수 있다.

• 브라우저 요청이 Gateway까지 도달했는가
• Gateway에서 4xx가 났는가
• Lambda integration에서 5xx가 났는가
• CORS preflight가 실패했는가
• stage 배포가 누락되었는가

이 정보는 Lambda 로그만으로는 부족할 수 있다.

Gateway access log와 metric은 요청 경로를 좁히는 데 도움이 된다.

백엔드 교체 가능성

API Gateway나 API용 CloudFront를 앞단에 두면 클라이언트 URL을 유지한 채 백엔드를 바꿀 여지가 생긴다.

처음에는 Lambda로 시작했다가 일부 endpoint를 상주 서버로 옮길 수도 있다.

반대로 상주 서버의 일부 기능을 Lambda로 분리할 수도 있다.

프론트엔드가 직접 각 백엔드 주소를 알게 만들면 교체가 어려워진다.

Gateway는 클라이언트와 백엔드 사이의 안정적인 계약 역할을 할 수 있다.

Gateway도 복잡도다

물론 Gateway는 공짜가 아니다.

설정해야 할 것이 늘어난다.

• resource
• method
• integration
• CORS
• stage deployment
• logging
• permissions

작은 API 하나라면 과할 수 있다.

따라서 API Gateway를 둘지는 필요한 운영 기능을 기준으로 판단해야 한다.

단순 HTTP 호출만 필요하면 더 가벼운 선택지도 있다.

하지만 브라우저 기반 콘솔, 여러 endpoint, CORS, 로그, 보호 정책이 필요하다면 Gateway는 충분히 가치가 있다.

정리

API Gateway는 단순한 Lambda 프록시가 아니다.

운영 콘솔에서는 다음을 담는 경계가 된다.

• CORS와 preflight
• path/method 라우팅
• access log
• 스로틀링
• 인증 확장성
• 백엔드 교체 가능성

중요한 것은 Gateway를 쓰느냐 마느냐가 아니다.

API 앞단에 어떤 운영 정책을 둘 것인가다.

그 정책이 필요하다면 API Gateway는 단순 프록시 이상의 역할을 한다.

함께 볼 GitHub 저장소

• practical-system-design-playbook