API 게이트웨이

API 게이트웨이란

API 게이트웨이(API gateway)는 클라이언트의 API 요청을 받는 앞단 서버다. 요청을 받아 보안·제한 정책을 적용하고, 알맞은 백엔드 서비스로 넘긴 뒤, 결과를 클라이언트에 돌려준다. 서비스가 여러 개로 쪼개진 마이크로서비스 구조에서 클라이언트가 서비스마다 주소를 알 필요 없게 하는 단일 진입점이다.

모든 요청이 지나가는 자리라서, 서비스마다 반복해야 할 공통 관심사(인증, 레이트 리밋, 로깅)를 한곳에 모을 수 있다.

기능

요청 하나가 지나는 순서

flowchart TB
  c["클라이언트"] -->|"HTTP 요청"| s1
  subgraph gw["API 게이트웨이"]
    s1["1. 요청 파싱, 속성 검증 (헤더·파라미터 형식)"] --> s2["2. 허용·차단 목록 확인 (IP, 클라이언트 ID)"]
    s2 --> s3["3. 신원 제공자(IdP)에 물어 인증·인가"]
    s3 --> s4["4. 레이트 리밋 규칙 적용"]
    s4 -->|"한도 초과"| r429["429로 거절"]
    s4 --> s5["5. 경로 매칭으로 대상 서비스 찾기 (서비스 디스커버리)"]
    s5 --> s6["6. 요청을 서비스의 프로토콜로 변환해 전달"]
    s6 --> s7["7. 오류 처리: 오래 실패하는 서비스는 회로 차단"]
    s7 --> s8["8. 로그·지표 기록, 필요하면 응답 캐시"]
  end
  s8 -->|"응답"| c

앞의 검사들은 싼 것부터, 그리고 거절할 수 있는 것부터 둔다. 형식이 틀린 요청에 인증 서버를 부를 필요는 없다.

쓰임

리버스 프록시, 로드 밸런서와의 차이

세 가지 모두 클라이언트와 서버 사이에 서므로 기능이 겹친다. 무엇을 주된 목적으로 두느냐로 구분한다.

로드 밸런서는 로드 밸런서, 리버스 프록시는 프록시에 따로 정리했다. 하나의 제품이 셋을 겸하기도 한다. Nginx나 Envoy는 설정에 따라 세 역할을 모두 한다.

서비스 메시, 공통 라이브러리와의 차이

서비스 메시(service mesh) 는 서비스와 서비스 사이(east-west) 통신을 맡는 인프라 계층이다. 각 서비스 옆의 프록시(Envoy 같은 사이드카, 또는 Istio 앰비언트 모드처럼 노드 단위 프록시)가 데이터 평면으로 트래픽을 대신 주고받고, 제어 평면(Istio의 istiod 등)이 라우팅 규칙·인증서·정책을 내려 준다. 애플리케이션 코드는 그대로 두고 mTLS, 재시도·타임아웃·서킷 브레이커, 트래픽 분할(카나리), 지표·트레이스를 얻는다.

셋은 대체재가 아니라 층이 다르다. 외부 요청은 게이트웨이가 받고, 내부 호출은 메시나 라이브러리가 다룬다. 서비스가 한 언어로 몇 개뿐이면 라이브러리로 충분하고, 여러 언어의 서비스가 많아져 공통 정책을 코드 밖에서 강제해야 할 때 메시를 들인다. 사이드카와 제어 평면의 구조는 로드 밸런서, 마이크로서비스의 공통 관심사 처리는 마이크로서비스 아키텍처에 있다.

함께 쓰는 배치

flowchart TB
  net["인터넷"] --> l4["L4 로드 밸런서<br/>IP 기반 분산, HTTP를 열어 보지 않음"]
  l4 --> a["(a) L7 로드 밸런서"]
  l4 --> b["(b) API 게이트웨이"]
  a -->|"경로로 서비스 분기"| sa["서비스들 (각자 인증·제한)"]
  b -->|"인증·레이트 리밋·캐시를 처리하고 분기"| sb["서비스들 (비즈니스 로직만)"]

작고 단순한 서비스는 로드 밸런서 하나로 충분하다. 서비스와 클라이언트 종류가 늘면 게이트웨이를 들인다.

게이트웨이 설계에서 자주 정하는 것들이다.

• 외부용과 내부용을 나눈다. 인터넷에서 오는 요청을 받는 외부 게이트웨이(인증, 레이트 리밋, 과금)와 서비스끼리 부르는 내부 게이트웨이(라우팅, 관측)는 정책과 부하가 다르다.
• 큰 파일은 게이트웨이를 거치지 않는다. 게이트웨이는 짧은 요청에 맞춰져 있어 수백 MB 업로드·다운로드가 연결과 메모리를 오래 붙잡는다. 게이트웨이는 임시 토큰이 붙은 다운로드 URL만 발급하고, 파일은 스토리지나 CDN에서 직접 받게 한다(S3 사전 서명 URL과 같은 방식).
• 오케스트레이션을 넣지 않는다. 여러 서비스 호출 순서와 비즈니스 규칙을 게이트웨이에 넣으면, ESB(엔터프라이즈 서비스 버스)에 로직을 몰아 넣었다가 중앙 병목과 변경 지옥이 된 SOA 시절을 되풀이한다. 게이트웨이는 「똑똑한 끝점, 단순한 파이프」에서 파이프 쪽에 머문다.
• 유료 API면 계량(metering)이 게이트웨이의 일이다. 키별 호출 수를 세어 요금제 한도와 청구에 쓴다.

한계와 위험

• 단일 장애점과 병목. 모든 요청이 지나가므로 여러 인스턴스로 띄우고 용량을 피크 기준으로 잡는다.
• 지연 한 홉. 모든 요청에 네트워크 홉과 처리 시간이 더해진다.
• 비즈니스 로직이 스며들기 쉽다. 응답 조합과 변환이 늘면 게이트웨이가 또 하나의 모놀리스가 된다. 화면별 조합은 BFF로 빼는 편이 낫다.
• 우회 경로. 서비스가 게이트웨이를 거치지 않고도 열려 있으면 게이트웨이의 인증이 무의미해진다. 내부망 격리나 mTLS로 막는다.

정리

• API 게이트웨이는 마이크로서비스 앞의 단일 입구로, 라우팅과 공통 정책(인증·제한·변환·관측)을 맡는다.
• 요청은 검증 → 차단 목록 → 인증 → 레이트 리밋 → 라우팅 → 변환 순으로 지나간다.
• 리버스 프록시는 숨기기, 로드 밸런서는 나누기, 게이트웨이는 API 호출 관리가 주목적이다.
• 게이트웨이가 무거워지면 단일 장애점이자 새 모놀리스가 된다. 얇게 유지한다.

관련 노트: 로드 밸런서, 프록시: 포워드 프록시와 리버스 프록시, 인증·인가 로직은 어디에 두나, BFF (Backend For Frontend), 대규모 트래픽에서 서비스를 지키는 설계, 쿠버네티스 위 웹 서비스의 요청 경로, 아키텍처와 API 계층의 진화