API Architecture

REST, gRPC, GraphQL, WebSocket, Webhook

REST부터 gRPC, GraphQL, WebSocket, Webhook, SSE, MQTT, Kafka까지

프로토콜(HTTP/WS/UDP/TCP/QUIC) × 패턴(요청-응답/스트림/이벤트) 시각으로!

API 아키텍처는 “무엇을 어떻게 주고받느냐(데이터 모델 & 프로토콜)”와 “언제/어떤 방향으로 흐르느냐(패턴 & 전송)”의 조합입니다. 아래 글은 실무에서 자주 쓰는 것부터 놓치기 쉬운 것까지 대표 아키텍처/프로토콜/패턴을 빠짐없이 묶어 개념을 정리하고, 선택 가이드를 제시합니다.

큰 지형 먼저 보기

요청-응답(Req/Res): 클라이언트가 요청하면 서버가 응답 (REST, GraphQL, gRPC Unary, SOAP, JSON-RPC, XML-RPC, OData 등)

푸시·스트리밍/양방향: 서버→클라 푸시 또는 양방향 스트림 (WebSocket, SSE, gRPC Streaming, RSocket, WebTransport, WebRTC DataChannel)

이벤트/메시징(비동기): 브로커를 통한 발행-구독·스트림 (MQTT, AMQP/RabbitMQ, NATS, Apache Kafka, Pulsar, STOMP, JMS)

콜백 패턴: 서버가 클라이언트의 공개 엔드포인트를 호출 (Webhooks)

카테고리별 정리

1) HTTP 기반 요청-응답 스타일

REST
리소스(URI)와 HTTP 메서드(GET/POST/PUT/DELETE) 중심. 캐시/프록시 친화적, 진입장벽 낮음. 스키마는 관습(OpenAPI)로 관리.

GraphQL
클라이언트가 “원하는 필드만” 선언적으로 질의. 과다/과소 응답 해소, 스키마가 타입으로 엄격. 캐싱/권한/성능 설계가 관건. 구독(Subscriptions)은 보통 WebSocket 또는 SSE로.

gRPC (HTTP/2/3)
기본적으로 Protocol Buffers(바이너리) 사용. Unary/서버 스트리밍/클라 스트리밍/양방향 스트리밍 지원. 마이크로서비스 간 고성능·정형 통신에 강함. 브라우저는 gRPC-Web 필요.

SOAP
XML+WSDL 기반의 전통적 엔터프라이즈 표준. 강한 계약과 툴링, 복잡도와 오버헤드가 큼.

OData
REST 위에 표준화된 질의($filter, $select 등)를 더한 모델. 데이터 API를 빠르게 노출하기에 유리.

JSON-RPC / XML-RPC
경량 RPC 스타일. 단순 호출/응답에 적합, 생태계·스키마 관리 측면은 상대적으로 약함.

Falcor / tRPC(타입스크립트)
클라-서버 타입 공유로 DX를 높이는 접근. 팀/스택 제약 내에서 생산성↑ (표준 프로토콜은 아님).

HTTP Long-Polling
푸시 대체재. 연결 유지 비용이 있으나 방화벽/프록시 호환성↑, 레가시 환경에서 fallback로 활용.

2) 실시간 푸시·스트리밍

WebSocket
HTTP 업그레이드를 통해 양방향, 지속 연결. 채팅/콜라보/게임 등 상호작용 실시간에 최적.

SSE(Server-Sent Events)
서버→클라이언트 단방향 텍스트 스트림(text/event-stream). 구현 간단·프록시 친화. 실시간 알림/마켓 티커에 용이. 바이너리는 Base64 등 우회 필요.

gRPC Streaming
HTTP/2 스트림으로 서버/클라/양방향 스트리밍. 타입 안전·고성능 실시간 파이프.

RSocket
Reactive Streams 기반 양방향 상호작용(요청-응답/스트림/채널). 백프레셔 지원, 다양한 전송(WS, TCP, QUIC 등).

WebTransport(HTTP/3/QUIC)
차세대 전송. 신뢰·비신뢰(데이터그램) 선택 가능, 지연 민감 서비스에 유망(브라우저 지원 진행형).

WebRTC DataChannel
주로 P2P 저지연 데이터 전송. NAT/시그널링 복잡도 있지만, 브라우저 간 실시간에 강함.

3) 이벤트/메시징·스트리밍 (브로커 기반)

MQTT
경량 Pub/Sub, QoS(0/1/2)로 신뢰도 선택. IoT/임베디드에 표준급.

AMQP
메시지 라우팅/큐(예: RabbitMQ 0-9-1, AMQP 1.0). 트랜잭션성·라우팅 유연성↑, 엔터프라이즈 통신에 널리 사용.

NATS
초경량 고성능 Pub/Sub, 단순 운영과 스케일에 강점. 마이크로서비스 이벤트 버스 대안.

Apache Kafka
분산 로그(스트림) 저장소. 내구성/리플레이/대용량 처리. 실시간 파이프라인·이벤트 소싱 핵심 인프라.

Apache Pulsar
토픽·서브스크립션 모델과 세분화된 스토리지 계층. 지연·멀티테넌시·지리 분산에 강점.

STOMP / JMS
텍스트 기반 프로토콜(STOMP)과 자바 메시징 표준(JMS). 브로커 상호운용/레거시 연계에 활용.

4) IoT/산업용(제약 환경/현장 표준)

CoAP
UDP 기반 경량 REST. 제약 디바이스/로스 네트워크에 최적. Observe(변경 통지) 지원.