naver.HOW data lake by AI

API Architecture Styles

작성자

sp

in"의 한국어 번역은 "안"입니다.

Audience: CTOs, Platform/Backend Leads, Solution Architects, Product Engineering Managers
Authoring Date: 2025-11-06
Scope: REST, GraphQL, WebSocket, gRPC, MQTT, Serverless (FaaS + API Gateway/Edge)

TL;DR

  • 한 줄 요약: 모든 문제를 한 가지 API 스타일로 해결할 수 없다. 업무 요구(지연·처리량·일관성·보안·팀역량)와 운영 환경(브라우저, 모바일, IoT, 데이터센터/엣지)을 기준으로 혼합(Polyglot) 아키텍처를 설계하라.
  • 빠른 매칭:
    • CRUD 중심 B2B/B2C 백엔드: REST
    • 프런트 주도 데이터 조립 / N+1 방지 / 단일 엔드포인트: GraphQL (+ Dataloader)
    • 초저지연 실시간 상호작용: WebSocket (또는 gRPC 스트리밍)
    • 내부 마이크로서비스 간 고성능 RPC: gRPC (Protocol Buffers)
    • 저전력·간헐적 네트워크 IoT: MQTT (Pub/Sub, QoS, Retain)
    • 스파이크형 트래픽·이벤트 처리·엣지 확장: Serverless (함수형 + 게이트웨이)
  • 운영 팁: 스키마/계약 우선(Design‑First), 관측성(OTel) 표준화, 제로트러스트 보안, 캐싱/백프레셔/리트라이 정책 일관화.

1) 배경과 목적

API는 기업의 디지털 공급망이다. 본 백서는 6가지 대표 스타일의 특성과 운영 상의 트레이드오프를 비교·정리하고, 선택·혼합·마이그레이션을 위한 실무 지침을 제공한다.

2) 비교 개요 (한눈에 보는 매트릭스)

항목RESTGraphQLWebSocketgRPCMQTTServerless
주 용도CRUD, 통합프런트 주도 질의실시간 양방향내부 고성능 RPCIoT 메시징이벤트/스파이크 처리
전송HTTP/1.1, HTTP/2HTTP/1.1/2WS over TCPHTTP/2TCP (1883), TLS (8883)HTTP/1.1/2 + 게이트웨이
스키마OpenAPISDL (Schema)메시지 규약Proto (.proto)토픽 규약/AsyncAPI이벤트/계약(AsyncAPI+OpenAPI)
상태성무상태 권장무상태장기 세션무상태브로커 상태 관리무상태 함수
스트리밍SSE/HTTP2 가능서브스크립션(WS)기본양방향 스트림Retain/Last‑will이벤트 기반
캐싱CDN/ETag필드 단위 캐시 전략어려움호출 레벨브로커 레벨게이트웨이 레벨
브라우저 친화매우 높음매우 높음높음낮음(브라우저 직접 X)낮음높음
모바일/오프라인보통보통배터리 고려SDK 필요강점(경량)보통
학습 곡선낮음중간중간중간~높음중간낮음~중간
보안OAuth2/OIDC동일 + 쿼리 제한토큰 + 세션 관리mTLS/JWTTLS + ACL게이트웨이 기반
관측성용이복잡도↑상시 트레이스 필요풍부한 메타브로커 메트릭게이트웨이 중심
비용예측 용이BFF 비용↑커넥션 비용↑인프라 효율↑브로커 비용요청 단가/콜드스타트

메모: GraphQL, WebSocket, MQTT는 메시지/쿼리 레벨 거버넌스가 중요하다(쿼리 복잡도 제한, 토픽 ACL, 메시지 스키마 버저닝 등).

3) 각 스타일 심층 가이드

3.1 REST — Representational State Transfer

언제 쓰나: 범용 CRUD, 외부 파트너 통합, 캐싱이 중요한 공개 API.
핵심 패턴:

  • URI 리소스 모델링: /orders/{id}
  • 표준 메서드: GET/POST/PUT/PATCH/DELETE
  • 계약 우선(OpenAPI): 문서→스텁→테스트 자동화
  • Idempotency 키(POST 멱등화), ETag/Cache‑Control
  • 에러 표준화: RFC7807(Problem Details)
    반패턴:
  • 동사형 엔드포인트 남발, 과도한 중첩, 1:N 채집(N+1) 미해결, 페이지네이션/정렬 미정의.
    스니펫 (OpenAPI 일부):
paths:
  /orders/{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200': { description: OK }

3.2 GraphQL — Query Your Data with Precision

언제 쓰나: 프런트가 다양한 화면에서 필드 단위로 데이터 조립해야 할 때, 오버/언더페치 최소화.
핵심 패턴:

  • 단일 엔드포인트: /graphql
  • 스키마 우선(SDL) + 코드생성 + Dataloader로 N+1 완화
  • 쿼리 복잡도 제한/Depth 제한
  • Persisted Query로 캐싱/보안 향상
  • Federation/BFF로 팀 경계 정렬
    반패턴:
  • 무제한 임의 쿼리 허용, 거대한 리졸버에 비즈 로직 혼합.
    스니펫 (SDL):
type Order { id: ID!, total: Int!, items: [Item!]! }

3.3 WebSocket — Instant, Two‑Way Interaction

언제 쓰나: 실시간 알림, 협업 편집, 게임/트레이딩, XR/미디어 제어.
핵심 패턴:

  • 토픽/룸 추상화, 백프레셔 및 레이트리밋
  • 연결 수 관리(샤딩, 팬아웃), 상태 동기화 프로토콜
  • 세션 재연결/재인증
    반패턴:
  • 서버 브로드캐스트 남발, 메시지 포맷 표준 없음, 장애 격리 미흡.
    메시지 예:
{ "type":"presence","user":"u1","status":"online" }

3.4 gRPC — High‑Speed Remote Procedure Calls

언제 쓰나: 마이크로서비스 간 레이턴시 민감, 타입 안정성·양방향 스트림 필요.
핵심 패턴:

  • .proto 계약 우선 + 멀티랭 SDK 생성
  • HTTP/2 멀티플렉싱 + mTLS
  • Gateway로 REST/JSON 변환 병행
    반패턴:
  • 외부 브라우저 직접 노출, 스키마 없거나 무분별한 서비스 확장.
    스니펫 (proto):
service OrderSvc { rpc Get(OrderId) returns (Order); }

3.5 MQTT — Lightweight Messaging for IoT

언제 쓰나: 저전력·간헐 연결 디바이스, 센서/액추에이터 제어, 수십만 장치 팬‑인.
핵심 패턴:

  • 토픽 설계: site/{id}/device/{id}/telemetry
  • QoS 0/1/2 선택, Retain 메시지, Last‑Will
  • 브로커 클러스터링 + ACL, 인증/권한 토큰
    반패턴:
  • 와일드카드 남발, 토픽에 PII 포함, 브리지 루프.

3.6 Serverless — Redefining Scalability

언제 쓰나: 이벤트 중심·스파이크 트래픽·엣지 로직·백오피스 자동화.
핵심 패턴:

  • 함수 단일 책임 + 짧은 실행시간 + Idempotency
  • 콜드스타트 완화(프리워밍/프로비저닝), DLQ/재시도
  • 인프라 as Code로 배포 표준화
    반패턴:
  • 장시간 CPU 바운드 작업, 대용량 연결 유지(WS 장기연결).

4) 하이브리드(Polyglot) 레퍼런스 패턴

  • REST + WebSocket: CRUD는 REST, 변경 이벤트/협업은 WS.
  • GraphQL Gateway + gRPC: 외부는 GraphQL, 내부는 gRPC로 서비스 경계 명확화.
  • MQTT + Serverless: IoT 텔레메트리는 MQTT, 서버리스가 규칙/ETL 처리.
  • REST + SSE: 구독이 간단하면 WS 대신 SSE.

ASCII 다이어그램(예: GraphQL↔gRPC):

[Web/Mobile] --HTTP--> [GraphQL Gateway] --gRPC--> [Order Svc]
                                               └--gRPC--> [Inventory Svc]

5) 비기능 요구사항(NFR) 맵핑

  • 지연/처리량: gRPC/WebSocket > REST > GraphQL(게이트웨이 비용 포함)
  • 일관성: 활용 패턴에 따라; 이벤트소싱 시 멱등·재처리 설계 필수
  • 가용성: 브로커/게이트웨이 단일장애지점 제거(HA)
  • 확장성: 상태 분리, 팬아웃/샤딩, 토픽·키 파티셔닝
  • 비용: 캐싱·콜레스·배치·샘플링, 서버리스 요청/GB‑sec 모델 주의

6) 보안·거버넌스 체크리스트

  • AuthN/AuthZ: OIDC/OAuth2(+PKCE), mTLS(내부), 토큰 수명 단축·회전
  • 권한 범위: 스코프·리소스 기반, RLS(DB) 연동
  • GraphQL: 쿼리 깊이/복잡도 제한, 필드 권한, Persisted Query
  • WebSocket: 재연결 시 토큰 재검증, 메시지 스키마 서명(optional)
  • gRPC: SPIFFE/SPIRE로 워크로드 아이덴티티, protobuf 버저닝
  • MQTT: 토픽 ACL, 디바이스 증명(증서/사전 공유키), LWT 정책
  • 서버리스: 최소권한 IAM, 환경변수/시크릿 관리, 큐/토픽 격리

7) 관측성(Observability)·신뢰성

  • 표준화: OpenTelemetry(Trace/Metric/Log) 일원화
  • RED/USE 지표: Rate, Error, Duration / Utilization, Saturation, Errors
  • 계약 테스트: Pact(REST/gRPC), SDL 검증(GraphQL), AsyncAPI(이벤트)
  • 혼잡 제어: 타임아웃·리트라이·서킷브레이커·백프레셔·큐 적체 알람
  • SLO/에러 등급: 사용자 영향 기반 에러 카탈로그, 에러 예산 운영

8) 의사결정 트리 (텍스트 버전)

  1. 브라우저/파트너 호환 & 캐싱 최우선? → REST
  2. 프런트가 화면별 필드 조립 필요? → GraphQL (Persisted Query + Dataloader)
  3. <100ms 양방향 상호작용? → WebSocket (또는 gRPC 스트림)
  4. 서비스 간 강타입·저지연? → gRPC (+ Gateway)
  5. 저전력·간헐 연결 디바이스? → MQTT
  6. 이벤트/스파이크·엣지 실행? → Serverless
  7. 둘 이상 해당? → 하이브리드 패턴 채택 (게이트웨이/브로커 중심)

9) 사례별 추천(시나리오)

  • B2C 커머스 웹앱: REST(상품/주문) + GraphQL(BFF) + WebSocket(재고 알림)
  • B2B 통합: REST(OpenAPI 계약) + gRPC(내부) + OIDC
  • 트레이딩/게임: WebSocket(매치/상태) + gRPC(서비스) + 카프카/큐 백프레셔
  • IoT 텔레메트리: MQTT(디바이스) + Serverless(ETL/규칙) + REST(관리)
  • XR/미디어 제어(예시): gRPC(렌더/트래킹 내부) + WebSocket(오퍼레이터 UI 실시간) + REST(프로젝트/자산 관리)

10) 마이그레이션 플레이북

  • Strangler Fig: 새 게이트웨이/GraphQL로 앞단 감싸고, 내부를 gRPC/이벤트로 단계적 분리
  • 계약 우선 전환: OpenAPI/Proto/SDL 저장소 단일 소스화 + 코드생성 파이프라인
  • 데이터 경계: Bounded Context 별 API 경계 재정의, 이벤트 카탈로그 구축
  • 위험 통제: 트래픽 미러링, 카나리, 다크 론칭, 리버서블 배포

11) 구현 체크리스트 (샘플)

공통

  • Design‑First 스키마 저장소(OpenAPI/Proto/SDL/AsyncAPI)
  • 표준 에러 모델(RFC7807 등) & 추적 상관 ID
  • Idempotency/리트라이/타임아웃 정책 표준화
  • 보안: 최소권한, 키/증명서 회전, 토큰 수명/철회
  • 관측성: OTel, 대시보드, 알람, 합성 모니터링

REST

  • 페이징/정렬/필터 표준, ETag/캐시, 멱등키

GraphQL

  • 쿼리 복잡도 제한, Persisted Query, Dataloader, Federation/BFF 경계

WebSocket

  • 메시지 규약/버전, 방/토픽 설계, 재연결/토큰 재검증, 백프레셔

gRPC

  • Proto 버저닝, Gateway 변환, mTLS, Deadline/Retry, Health/Reflection

MQTT

  • 토픽 네이밍/ACL, QoS/Retain/LWT, 브로커 HA, 브리지 설정

Serverless

  • 함수 타임아웃/메모리 설정, DLQ/재시도, 콜드스타트 완화, IaC

12) 비용 모델링(간단 예시)

  • REST/GraphQL: 요청수 × 평균 응답시간 × 인스턴스 단가 (캐시 적중률 변수)
  • WebSocket: 동시 연결수 × 평균 세션시간 × 커넥션 단가
  • gRPC: 처리량 당 인스턴스 적재율↑ → 단위 요청 비용↓
  • MQTT: 브로커 클러스터 비용 + 메시지/토픽 수
  • Serverless: 호출수 × (GB‑sec) + 아웃바운드 네트워크

13) 문서화·도구·프로세스

  • 계약·스키마: OpenAPI, GraphQL SDL, Protocol Buffers, AsyncAPI
  • 코드생성: openapi‑generator, buf, graphql‑codegen
  • 검증/테스트: spectral(lint), pact, k6/vegeta(부하), graphql‑shield
  • CI/CD: 계약 변경 감시 → 스텁/SDK 재생성 → 배포

14) 부록 A — 용어

  • BFF: Backend For Frontend. 채널별 맞춤 API.
  • 멱등(Idempotent): 반복 호출 시 동일 결과 보장.
  • 백프레셔: 송수신 속도 불일치 완화 메커니즘.

15) 부록 B — RFP/RFI 체크 질문 템플릿

  • 귀사의 API는 어떤 스키마/계약 표준을 사용합니까? (OpenAPI/Proto/SDL/AsyncAPI)
  • **관측성(OTel)**과 SLO 체계는 갖추고 있습니까?
  • 보안 정책(토큰 수명, 키 회전, mTLS, ACL)은?
  • 버저닝/하위호환 전략은?
  • 백업/DR 및 지역 간 복제 정책은?

결론

단일 해법은 없다. 도메인 요구를 기준으로 스타일을 선택하고, 필요 시 혼합하라. 그 과정에서 계약 우선, 관측성, 거버넌스를 공통 토대로 삼으면 장기 유지보수 비용이 급감한다.

코멘트

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

더 많은 게시물