API Gateways & Edge Logic

1. Overview

API 게이트웨이와 엣지 로직(API Gateways & Edge Logic)은 수백 개의 마이크로서비스가 외부로 흩뿌려져 모바일 앱(Client)이 도대체 어느 서버를 찔러야 할지 몰라 방황하는 대혼란을 끝내고, 외부 세계와 내부 클러스터 사이에 완벽한 통제선(Facade)을 구축하는 최전방 방어막을 해부합니다.

학습자는 모바일 앱이 10개의 서버에 각기 다른 API(HTTP)를 쏘다 배터리가 광탈하는 비효율을 깨닫고, 단 1번의 호출(Call)로 여러 서비스의 데이터를 백엔드에서 조합하여 내려주는 BFF(Backend for Frontend) 패턴의 우아함을 뜯어봅니다. 나아가 모든 트래픽이 통과하는 유일한 관문인 **API 게이트웨이(API Gateway)**에서 인증(JWT), 속도 제한(Rate Limiting), 로깅을 한 번에 처리하여 뒷단 서비스들의 짐을 덜어주는 '오프로딩(Offloading)'의 역학을 장악합니다. 마지막으로, 단일 장애점(SPOF)이라는 게이트웨이의 치명적 아킬레스건을 인식하고 스케일아웃(Scale-out) 아키텍처로 방어하는 역량을 확보합니다.

2. Scope & Boundaries

In-Scope

• API Gateway: 클라이언트 요청의 단일 진입점(Single Entry Point), 라우팅(Routing).
• Edge Functions (Cross-cutting Concerns): Authentication (JWT 검증), Rate Limiting (속도 제한), SSL Termination.
• BFF (Backend for Frontend): 클라이언트 맞춤형 API 조합(Composition) 및 페이로드 축소.
• GraphQL vs REST at Edge: 클라이언트 주도 데이터 패칭(Over-fetching 방지).

Out-of-Scope

• Service Mesh (내부 통신망): 클러스터 내부 마이크로서비스 간 통신 제어 $\rightarrow$ 07-06-04 Service Mesh 영역.
• OAuth 2.0 / OIDC 상세 구현: 토큰 발급 로직 $\rightarrow$ 08-04 Authentication & AuthZ 영역으로 위임.

Boundaries

• API Gateway vs Ingress vs Service Mesh: 인그레스(Ingress)는 "URL 경로에 따라 어느 서비스로 보낼지" 결정하는 멍청한(Dumb) L7 라우터입니다. API 게이트웨이는 인그레스의 상위 호환으로, 비즈니스 레벨의 로직(JWT 토큰 뜯어보기, A와 B 서비스 데이터 합치기, 초당 100회 제한 걸기)을 수행하는 똑똑한(Smart) 문지기입니다. 반면 서비스 메시는 문지기가 아니라 '성 내부의 주민들(서비스들)끼리 대화'할 때 감시하는 헌병대입니다. 이 3가지 엣지/네트워크 계층의 역할을 헷갈려서 인그레스에 비즈니스 코드를 우겨넣는 안티 패턴을 명확히 경계 짓습니다.

3. Counterexample

• 클라이언트의 스파게티 호출 (Chatty I/O): 유저가 '내 정보' 화면을 열었습니다. 모바일 앱은 유저 닉네임을 가져오기 위해 User API를, 포인트 잔액을 위해 Point API를, 최근 쿠폰을 위해 Coupon API를 호출합니다. 앱이 3번의 HTTP 네트워크를 타면서 화면 렌더링이 2초나 걸리고 배터리가 박살 납니다. 중간에 API 게이트웨이나 BFF를 두어 클라이언트는 단 한 번만 호출하고, 기가비트 이더넷(내부망)으로 묶인 백엔드끼리 빠르게 조합(Composition)하여 던져주는 패턴을 무시한 모바일 성능의 무덤입니다.
• 보안 로직 중복의 늪: 50개의 마이크로서비스가 각자 소스 코드 안에 verifyJWT() 함수를 들고 있습니다. 보안팀에서 "JWT 서명 알고리즘을 RS256에서 HS512로 바꿔라"라고 지시하자, 50개 팀이 각자 코드를 수정하고 50번의 배포를 하다 3개 팀이 뻑나서 장애가 터집니다. 공통 관심사(Cross-cutting Concerns)인 '인증'을 엣지(API Gateway)에서 한 방에 처리하고, 뒤쪽 서비스들에겐 검증이 끝난 User-ID 헤더만 넘겨주는 오프로딩(Offloading) 철학을 몰각한 복잡도 폭발입니다.

4. Prerequisites

• 인증 인가 기초 (Basic): JWT(JSON Web Token)의 구조. (08-04 Authentication & AuthZ)
• 부하 통제 원리 (Basic): Rate Limiting 개념. (07-05-03 Capacity & Resource)

5. Learning Map

6. Learning Topics

Basic

Core Topic 01: 무법지대의 보안관, 단일 진입점 (The Single Entry Point)

• Why to Learn: MSA로 쪼개진 수십 개의 백엔드 서비스 구조를 클라이언트(모바일 앱)에게 숨기고, 캡슐화(Encapsulation)를 통해 백엔드 아키텍처 리팩터링의 자유도를 확보하기 위함입니다.
• What to Learn:
  • Concepts: API Gateway, Facade Pattern (퍼사드 패턴), Tight Coupling (강결합), Encapsulation (캡슐화), Reverse Proxy.
  • Skills: NGINX 또는 Kong/KrakenD를 활용한 API -> Backend 라우팅 설정.
• How to Learn:
  • 1단계: 노출의 재앙: 앱이 User API(10.0.1.2)와 Order API(10.0.1.3)를 직접 찌릅니다. 내일 백엔드팀이 User와 Order를 합쳐서 UserOrder API(10.0.1.4)로 시스템을 리팩터링했습니다. 모바일 앱은 구버전 호환성이 깨져서 크래시가 납니다(강결합).
  • 2단계: 퍼사드(Facade)의 기적: 앱은 오직 api.app.com (API Gateway) 하나만 찌릅니다. 뒷단에서 백엔드가 2개로 쪼개지든 10개로 쪼개지든, Gateway가 라우팅 룰만 스윽 바꿔주면 앱은 1줄의 코드 수정 없이 정상 동작하는 캡슐화의 위력을 해부합니다.
• Implement: API Gateway 라우팅 및 캡슐화 시뮬레이션(CLI). Client가 무조건 /api/v1/profile 로 GET을 날림. Gateway 로직 안에서 이를 가로채어, 구버전에서는 Legacy_User_Service를 호출하고, 플래그(Flag) 전환 후에는 New_User_Auth_Service로 내부 라우팅을 조용히 변경하여 클라이언트에 동일한 포맷을 리턴하는 투명(Transparent) 릴레이 렌더링.

Recommended

Core Topic 02: 디바이스 맞춤형 집사, BFF 패턴 (Backend for Frontend)

• Why to Learn: 범용 REST API 하나로 모바일(작은 화면)과 웹 어드민(큰 화면)을 동시에 억지로 맞추려다 발생하는 오버페칭(Over-fetching)과 모바일의 챗티(Chatty) 통신 지옥을 박살 내기 위함입니다.
• What to Learn:
  • Concepts: BFF (Backend for Frontend), API Composition (조합), Over-fetching / Under-fetching, Chatty I/O, Aggregation (집계).
  • Skills: 백엔드 3개의 데이터를 비동기로 동시 호출하여 클라이언트 요구사항에 맞게 JSON을 정제(Filtering)해 주는 BFF 레이어 구축.
• How to Learn:
  • 1단계: Chatty I/O (수다쟁이 모바일): 상품 상세 페이지를 그리려면 상품 정보, 리뷰 3개, 연관 상품 리스트가 필요합니다. 모바일 앱이 3번의 HTTP 통신을 합니다. 3G 통신망에서 화면이 뜨는 데 3초가 걸립니다.
  • 2단계: BFF (맞춤형 백엔드): 모바일 앱을 위한 전용 BFF 서버(Mobile BFF)를 하나 둡니다. 모바일 앱은 BFF에게 단 1번만 요청합니다. BFF 서버는 내부 기가비트망을 타고 백엔드 3개를 동시에 찔러(비동기) 데이터를 긁어온 뒤, 모바일 화면에 딱 필요한 텍스트만 조립(Aggregation)해서 예쁜 JSON 1개로 압축해 던져주는 극강의 프론트엔드 최적화를 뜯어봅니다.
• Implement: API Composition(조합) 파이썬 스크립트. MobileClient가 MobileBFF에 1번 요청. MobileBFF 내에서 asyncio.gather()를 통해 User_SVC, Order_SVC, Review_SVC에 동시에 비동기 HTTP GET 발사. 응답들을 받아 용량이 큰 필드(예: review_image_url)는 가지치기(Trim)하고 오직 Mobile 렌더링에 필요한 필드만 묶은 Combined_JSON을 리턴하는 데모.

Practical

Core Topic 03: 공통 관심사 짬처리, 엣지 오프로딩 (Edge Offloading)

• Why to Learn: MSA로 분리된 수십 개의 팀이 각자 '인증 로직'과 '보안 로직'을 짜느라 귀중한 비즈니스 개발 시간을 낭비하는 끔찍한 코드 중복을 인프라 레이어로 걷어내기 위함입니다.
• What to Learn:
  • Concepts: Offloading (오프로딩/위임), Cross-cutting Concerns (공통 관심사), JWT Authentication, Rate Limiting (속도 제한/Token Bucket), SSL Termination.
  • Skills: API Gateway 단에서 들어오는 HTTP 헤더의 JWT 서명을 검증하고 백엔드로 통과시키는 인증 프록시(Auth Proxy) 설정.
• How to Learn:
  • 1단계: 코드 중복의 악몽: 주문팀, 장바구니팀, 리뷰팀 모두 Java 런타임에 JWT 검증 라이브러리를 추가하고, 유효기간(Exp)이 지났으면 401을 뱉는 코드를 똑같이 복붙(Ctrl+C, V)했습니다. 라이브러리에 취약점이 발견되면 3팀 모두 밤새워 패치하고 배포해야 합니다.
  • 2단계: 문지기에게 위임(Offloading): API Gateway에 플러그인(Plugin) 하나만 켭니다. 유저 트래픽이 들어올 때 Gateway가 무조건 JWT 서명을 까봅니다. 가짜면 거기서 바로 401 Unauthorized로 튕겨버립니다. 진짜면 JWT 안의 User-ID를 쏙 뽑아서 HTTP 헤더(X-User-Id: 123)에 예쁘게 담아 뒷단 백엔드에 넘겨줍니다. 뒷단 백엔드는 인증 걱정 없이 비즈니스 로직만 짜는 완벽한 관심사 분리를 해부합니다.
• Implement: 엣지 인증 필터(Auth Proxy) 로직. Gateway 함수가 Header(Authorization: Bearer <token>) 수신. 토큰 디코딩 실패 시 즉각 [401 DENIED] 반환. 성공 시 토큰 안의 페이로드에서 sub(user_id)를 추출하고, 헤더에 X-User-Id를 주입(Inject)하여 뒤쪽의 더미 Business_API_Func()로 통과시키는 래핑 로직 렌더링.

Advanced

Core Topic 04: 단일 장애점의 공포와 GraphQL (SPOF & GraphQL at the Edge)

• Why to Learn: 훌륭한 Gateway 패턴이 역으로 "Gateway 하나 죽으면 회사 전체가 마비되는" 단일 장애점(SPOF)으로 돌변하는 리스크를 방어하고, 클라이언트 데이터 요청의 극한 최적화인 GraphQL을 도입하기 위함입니다.
• What to Learn:
  • Concepts: SPOF (Single Point of Failure), Stateless Gateway, Horizontal Scaling, GraphQL (Query Language), Under-fetching 방지.
  • Skills: 게이트웨이 내부에 상태(Session)를 두지 않고 스케일아웃(Scale-out)이 가능하게 설계하기, GraphQL을 BFF로 활용하기.
• How to Learn:
  • 1단계: SPOF의 공포: 모든 트래픽이 Gateway를 거칩니다. Gateway CPU가 $100\%$를 치고 뻗으면 뒷단 백엔드 100개가 아무리 멀쩡해도 회사는 즉시 정전(Blackout)입니다. 이를 막기 위해 Gateway는 절대 세션(Session) 같은 상태를 저장하지 않는 순수 무상태(Stateless) 라우터로 짜서, 언제든 10대 20대로 횡적 확장(Scale-out)될 수 있어야 함을 뜯어봅니다.
  • 2단계: GraphQL이라는 궁극의 BFF: 기존 BFF는 백엔드 개발자가 일일이 "모바일용 API, 웹용 API"를 하드코딩해서 짜줘야 합니다. GraphQL을 Gateway(혹은 BFF)에 도입하면, 클라이언트(프론트)가 "나 이름이랑 최근 주문 3개만 줘"라고 쿼리(Query)를 쏘고 서버는 시킨 대로만 조합해서 줍니다. 프론트엔드가 데이터 통제권을 쥐어 백엔드 개발자의 병목을 없애버리는 엣지 패러다임 전환을 해부합니다.
• Implement: 무상태 게이트웨이 부하 분산 모델링. LoadBalancer 뒤에 Gateway_1, Gateway_2 배치. 유저 A의 1번 요청이 Gateway_1에서 처리되고, 2번 요청이 Gateway_2로 라우팅되어도 로그인(JWT 인증)이 완벽히 유지되는 무상태성(Stateless) 증명. (만약 Gateway에 메모리 세션 상태를 저장했다면 2번 요청 시 로그아웃되는 SPOF 크래시 현상 텍스트 비교).

7. Terminology

8. References

Primary

• [P1] CS2023 - Software Engineering (SE) - Software Architecture (Gateway and Facade)
• [P5] SFIA - Enterprise IT Architecture (ARCH) - API Integration

Secondary

• [Microservices Patterns] Chris Richardson - API Gateways and BFF
• [Building Microservices] Sam Newman - Integrating with Third-Party Software

Industry

• [AWS Architecture Blog] - API Gateway pattern versus the Direct client-to-microservice communication
• [SoundCloud Engineering Blog] - BFF (Backend for Frontend) Pattern

9. Final Checklist

Primary

• 클라이언트(모바일 앱)가 백엔드 마이크로서비스들의 개별 IP와 포트를 직접 호출(Direct Call)할 때 발생하는 극심한 강결합(Tight Coupling)을 API Gateway의 퍼사드(Facade) 패턴이 어떻게 끊어내는지 설명할 수 있는가?
• 모바일 기기의 느린 네트워크 환경(3G)에서 여러 API를 찔러야 하는 챗티(Chatty I/O) 문제를, BFF(Backend for Frontend)가 서버 내부망 기가비트 속도로 대신 조합(Composition)하여 1번의 호출로 줄여주는 원리를 증명할 수 있는가?

Secondary

• 모든 마이크로서비스 소스 코드 내부에 JWT 서명 검증 코드를 하드코딩하는 낡은 짓을 버리고, API Gateway 단에서 인증(Auth)을 오프로딩(Offloading)하여 백엔드로 X-User-Id 헤더만 넘겨주는 관심사 분리(Separation of Concerns)를 설계할 수 있는가?
• 블랙프라이데이 트래픽 폭주 시, 뒷단 백엔드(DB 등)가 감당할 수 있는 최대 부하를 보호하기 위해 API Gateway 단에서 토큰 버킷(Token Bucket) 알고리즘 등으로 속도 제한(Rate Limiting)을 쳐내는 지혈 전략을 논증할 수 있는가?

Industry

• 모든 트래픽이 거쳐 가는 API Gateway가 서버 다운 시 회사 전체를 마비시키는 단일 장애점(SPOF) 리스크를 식별하고, 내부에 어떠한 세션(Session)도 두지 않는 무상태(Stateless) 스케일아웃을 통해 이 리스크를 방어할 수 있는가?
• 클라이언트가 요구하는 데이터의 스펙(필드)이 매번 바뀌는 애자일 환경에서, 전통적인 BFF 패턴이 겪는 'API 신규 개발' 병목을 해소하기 위해 GraphQL을 엣지 게이트웨이에 도입하여 클라이언트가 쿼리 주도권을 갖게 하는 아키텍처를 평가할 수 있는가?