API는 서비스 간의 계약이다
마이크로서비스 환경에서 API는 단순한 인터페이스가 아니다. 서비스와 서비스, 서비스와 클라이언트 간의 계약(Contract) 이다. 계약이라는 표현이 중요한 이유는, 한번 외부에 공개된 API는 일방적으로 바꾸기 어렵기 때문이다. API를 어떻게 설계하느냐가 전체 시스템의 안정성과 진화 가능성을 결정한다.
API 설계 시 핵심 고려 요소
- 데이터 모델링: 어떤 리소스를 어떤 구조로 표현할 것인가
- 버저닝 전략: API가 변경될 때 기존 클라이언트를 어떻게 보호할 것인가
- 일관된 에러 모델: 에러가 발생했을 때 모든 서비스가 동일한 형태로 응답하는가
- 통신 방식 선택: REST, gRPC, Event-driven, GraphQL 중 어떤 것이 이 맥락에 맞는가
통신 패턴 개요
서비스 간 통신은 크게 동기(Synchronous) 와 비동기(Asynchronous) 로 나뉜다. 어떤 방식을 선택하느냐는 "응답을 바로 받아야 하는가"에 달려 있다.
| 방식 | 프로토콜 | 특징 |
|---|---|---|
| 동기 | REST (HTTP/JSON) | 요청-응답, 간단, 범용 |
| 동기 | gRPC (HTTP/2, ProtoBuf) | 고성능, 타입 안전, 스트리밍 |
| 비동기 | 메시지 브로커 (Kafka, RabbitMQ) | 느슨한 결합, 이벤트 기반 |
| 하이브리드 | REST + 이벤트 | 요청은 동기, 후속 처리는 비동기 |
REST API
REST는 웹 기반에서 가장 널리 쓰이는 API 스타일이다. HTTP를 그대로 활용하며, URL은 자원(Resource)의 위치를 나타내고 HTTP 메서드(GET, POST, PUT, DELETE)가 행위를 표현한다. JSON 기반 응답이 표준이며 캐싱, 보안, API 게이트웨이 연동이 쉽다.
단점: API 간 동기 의존성이 강하고, 여러 서비스의 데이터를 조합하는 복잡한 응답에는 불리하다. 호출 체인이 길어질수록 지연과 장애 전파 위험이 커진다.
gRPC
Google이 개발한 고성능 RPC(Remote Procedure Call) 프레임워크다.
- HTTP/2 기반: 멀티플렉싱(하나의 연결로 여러 요청 병렬 처리), 헤더 압축으로 네트워크 효율 향상
- Protocol Buffers: 바이너리 직렬화. JSON 대비 빠르고 용량이 작음. IDL로 인터페이스를 먼저 정의하므로 서비스 간 계약이 명확해짐
- 양방향 스트리밍: 클라이언트와 서버가 동시에 스트림으로 데이터를 주고받을 수 있음
단점: 브라우저에서 직접 호출이 어렵다. 브라우저 클라이언트가 필요하다면 gRPC-Web 레이어가 필요하다.
💡 Callout: REST vs gRPC 선택 기준
구분 REST gRPC 프로토콜 HTTP/1.1 (주로) HTTP/2 직렬화 JSON (텍스트, 사람이 읽을 수 있음) Protocol Buffers (바이너리, 빠름) 브라우저 지원 완전 지원 gRPC-Web 필요 스트리밍 제한적 서버, 클라이언트, 양방향 스트리밍 모두 지원 계약 명세 OpenAPI/Swagger .proto 파일 적합한 용도 외부 공개 API, 범용 내부 서비스 간 통신, 성능 중시 실무에서는 외부에 노출하는 API는 REST, 마이크로서비스 내부 통신은 gRPC를 선택하는 패턴이 일반적이다. gRPC는 특히 언어가 다른 서비스 간 통신에서 타입 안전성 덕분에 유용하다.
Event-driven (이벤트 기반)
서비스들이 이벤트를 발행(Publish)하고 구독(Subscribe)하는 방식으로 통신한다.
흐름 예시
1. Order Service → OrderCreated 이벤트 발행 (Kafka Topic에)
2. Inventory Service → 이벤트 구독, 재고 차감 수행
3. Notification Service → 이벤트 구독, 사용자 알림 발송
Order Service는 Inventory와 Notification 서비스가 어떻게 동작하는지 알 필요가 없다. 단지 이벤트를 발행하고 끝이다. 느슨한 결합과 비동기 처리가 핵심 장점이다.
단점: 트랜잭션 흐름을 추적하기 어렵고, 이벤트 순서 보장과 중복 처리 문제를 설계 단계에서 고려해야 한다.
API Gateway & BFF 패턴
API Gateway
외부 클라이언트의 단일 진입점(Single Entry Point) 역할을 하는 컴포넌트다.
- 인증/인가: 모든 요청에 대해 JWT 검증, OAuth2 토큰 확인
- 라우팅: 요청 URL, 헤더에 따라 적절한 내부 서비스로 전달
- Rate Limit: 클라이언트별 요청 속도 제한으로 서비스 보호
- 로깅/모니터링: 모든 트래픽의 중앙 기록점
API Gateway의 본질적인 가치는 "외부 세계"와 "내부 서비스 구조"를 분리한다는 점이다. 내부 서비스가 어떻게 나뉘어 있든, 외부 클라이언트는 단일 엔드포인트만 알면 된다.
BFF (Backend for Frontend)
BFF는 API Gateway에서 한 걸음 더 나아간 패턴이다. 프론트엔드 각 채널(웹, 모바일, IoT 등)에 최적화된 API 백엔드 레이어를 따로 두는 방식이다.
왜 BFF가 필요한가? 하나의 통합 API로는 다양한 클라이언트의 요구를 동시에 만족시키기 어렵다.
- Web: 대량 데이터, 풍부한 UI 구성을 위한 복합 응답
- Mobile: 네트워크 제약, 배터리 절약을 위해 응답 최소화
- IoT: 초경량 데이터, 단순한 명령/상태만 필요
각 채널마다 BFF를 두면, 해당 채널의 요구에 맞게 여러 마이크로서비스를 호출하고 데이터를 조합하고 변환해서 최적화된 응답을 만들 수 있다.
BFF의 주요 역할
- API Aggregation: 주문 상세 화면을 위해 User, Order, Product 서비스를 한 번에 호출해 하나의 응답으로 조합
- Data Transformation: 백엔드 데이터 구조를 프론트엔드가 원하는 DTO 형태로 변환
- Error Mapping: 각 서비스의 다양한 에러를 프론트엔드 표준 에러로 통일
- Caching: 모바일 성능 최적화를 위한 응답 캐싱
- Feature Flag / A/B Test: 프론트엔드 실험용 기능 분기
BFF 개발 시 주의할 점
- ❌ 비즈니스 로직을 과도하게 넣지 말 것. BFF는 "프론트 최적화 레이어"이지 Service Layer가 아니다.
- ❌ 서비스 간 데이터 강결합 금지. BFF는 조립자(Assembler) 역할이어야 한다.
- ✅ 프론트엔드 개발팀이 소유해야 한다. 그래야 프론트 개발 속도가 빨라진다.
마이크로서비스 내 API 통신 전략
분산 시스템에서 API 호출은 언제든 실패할 수 있다. 이를 전제로 설계해야 한다.
핵심 원칙
- 동기 호출 최소화: 동기 호출 체인이 길수록 장애 전파 범위가 커진다. 필요하지 않은 동기 의존성은 비동기로 전환한다.
- API 호출 체인 3 Hop 이하로 제한: A→B→C→D처럼 호출이 깊어지면 레이턴시가 쌓이고 장애 추적이 어려워진다.
- Circuit Breaker, Retry, Timeout 적용: 호출이 실패하거나 느릴 때 시스템을 보호하는 장치를 반드시 둔다.
- Observability(Trace/Log/Metric) 필수: 분산 호출 흐름이 보이지 않으면 장애 원인을 찾을 수 없다.
API 보안 Best Practice
| 항목 | 방법 |
|---|---|
| 인증/인가 | OAuth2 / JWT (서명된 토큰으로 상태 없이 검증) |
| Rate Limit | API Gateway 수준에서 IP 또는 사용자별 제한 |
| Input Validation | 모든 입력값 검증. SQL Injection, XSS 방어 |
| 전송 암호화 | HTTPS/TLS 기본 적용 |
| 서비스 간 인증 | Zero Trust 원칙 — "Never Trust, Always Verify" |
특히 Zero Trust 원칙은 내부 네트워크라고 해서 신뢰하지 않는다는 것을 의미한다. 서비스 A에서 서비스 B로 보내는 요청도 인증을 거쳐야 한다. 내부 네트워크가 침해되더라도 수평 이동(Lateral Movement)을 차단하기 위함이다.
요약: API는 단순한 기술 구현이 아니라 서비스 간 계약이다. 어떤 통신 방식을 선택하느냐(REST, gRPC, Event)는 해당 서비스의 요구사항과 트레이드오프를 따져서 결정해야 한다. API Gateway와 BFF는 외부 세계와 내부 서비스의 복잡성을 효과적으로 분리하는 구조다.
