Menu
Menu
Posts List
  1. REST API vs GraphQL:
    1. 개요
    2. 장점 & 단점
      1. REST API
      2. GraphQL
    3. 성능 & 캐시 비교
    4. 버전/스키마 진화
    5. 권한/보안
    6. 에러 처리
    7. 개발 경험(DX)
    8. “언제 무엇을 쓸까” 체크리스트
    9. 혼합(하이브리드) 전략
    10. 실무 팁
    11. 요약

REST API vs GraphQL

2025.09.30 SUNG9

REST API vs GraphQL:

개요

  • REST API: 리소스(엔드포인트) 중심. GET /users/1, POST /orders 처럼 HTTP 메서드와 경로로 표현.
  • GraphQL: 질의(Query) 중심. 클라이언트가 필요한 필드만 선언적으로 요청.

장점 & 단점

REST API

장점

  • 단순성/표준성: HTTP 표준(메서드/상태코드/캐시)과 잘 맞음.
  • CDN 캐시 친화적: GET /posts?page=1 같은 정형 URL 캐싱 용이.
  • 관찰성 쉬움: 엔드포인트별 트래픽/에러 모니터링이 직관적.
  • 권한/레이트리밋 단순: 엔드포인트 단위 제어가 쉬움.
  • 러닝 커브 낮음: 팀 온보딩 빠름, 도구/문서 풍부.

단점

  • 오버패칭/언더패칭: 필요한 필드만 받기 어려움 → 추가 요청 필요하거나 불필요 데이터 과다 포함.
  • 버전 관리 부담: v1, v2 등 다중 버전 공존/폐기 관리 필요.
  • N+1 호출: 화면 조립 시 다수 엔드포인트를 연쇄 호출하기 쉬움.
  • 스키마 계약 약함: OpenAPI로 보완 가능하지만 강제력은 팀 성숙도에 의존.

GraphQL

장점

  • 정밀 데이터 페칭: 필요한 필드만 선택 → 네트워크 효율↑, 모바일에 유리.
  • 단일 엔드포인트: 화면 하나를 한 번의 쿼리로 구성 가능(대개 /graphql).
  • 강한 스키마: 타입 안전/자동 문서화/툴링(GraphiQL, Codegen) 우수.
  • 버전리스 진화: 필드 추가/폐기(Deprecation)로 점진적 변경 수월.
  • 실시간 지원: Subscriptions(WebSocket)으로 실시간 업데이트 용이.

단점

  • 캐싱 난이도: HTTP 레벨 캐싱이 제한적 → 클라이언트/서버 캐시 계층 설계 필요.
  • 백엔드 성능 튜닝: 복잡 쿼리로 N+1/카디널리티 폭증 위험 → DataLoader/쿼리 제한 필수.
  • 보안/권한: 필드 단위 규칙 세분화 필요. 쿼리 비용 제한/깊이 제한 필요.
  • 관찰성 복잡: 단일 엔드포인트라 추적/메트릭 분리가 어려움(필드/리졸버 단위 관측 필요).
  • 러닝 커브/운영비: 스키마 설계·리졸버 최적화·도구 체인 도입 비용 발생.

성능 & 캐시 비교

  • REST
    • CDN/브라우저 캐시: 강함(Etag, Cache-Control).
    • 서버 비용: 단순한 read-heavy에 유리.
  • GraphQL
    • 클라이언트 캐시: Apollo/Relay의 정규화 캐시가 핵심.
    • 쿼리 비용 관리: 쿼리 화이트리스트, 깊이/복잡도 제한, 퍼시스턴트 쿼리 권장.

버전/스키마 진화

  • REST: /v1, /v2 병행 운영 → 디프리케이션 공지/마이그레이션 계획 필수.
  • GraphQL: @deprecated로 필드 단위 교체. 린(lean)한 점진적 이행 가능.

권한/보안

  • REST: 엔드포인트/메서드 단위 RBAC, 레이트 리밋, WAF/캐시 앞단에 두기 쉬움.
  • GraphQL: 필드/타입 단위 권한, 쿼리 비용/깊이 제한, 입력 검증, 퍼시스턴트 쿼리로 완화.

에러 처리

  • REST: HTTP 상태코드(4xx/5xx) 표준화.
  • GraphQL: data와 errors 동시 반환. 부분 실패/부분 성공 표현은 유연하지만 규약 합의 필요.

개발 경험(DX)

  • REST: OpenAPI + 코드생성 + Postman/Insomnia.
  • GraphQL: 스키마 우선 개발, GraphiQL/Playground, 타입세이프 코드생성, 스키마 린팅.

“언제 무엇을 쓸까” 체크리스트

상황 REST 선호 GraphQL 선호
단순 리소스 CRUD ✅
강력한 CDN 캐시 필요 ✅
여러 화면 조각을 한 번에 조립 ✅
모바일/저대역폭 최적화 ✅
제품 실험/필드 증감 잦음 ✅
팀 러닝 커브/운영 단순성 ✅
실시간 업데이트(구독) ✅
보안/레이트리밋을 L7 앞단에서 단순화 ✅

혼합(하이브리드) 전략

  • Read는 REST + CDN, 복잡한 화면 조립은 GraphQL.
  • GraphQL BFF(Backend For Frontend): 내부는 마이크로서비스/REST, 외부는 단일 GraphQL 게이트웨이.
  • 퍼시스턴트 쿼리 + 캐시 키 정책으로 GraphQL 캐싱 강화.

실무 팁

  • REST
    • OpenAPI/JSON:API로 규약 통일, ETag/Cache-Control 적극 사용.
    • 리소스 간 관계는 명확히 문서화(확장 쿼리 파라미터 기준).
  • GraphQL
    • DataLoader로 N+1 방지, 쿼리 복잡도/깊이 제한 설정.
    • 필드 Deprecation 정책과 스키마 체인지 가이드라인 운영.
    • 클라이언트 정규화 캐시(엔티티 id 정책) 필수.

요약

  • REST: 단순, 캐시 강함, 운영 용이. 화면 조립/데이터 정밀 제어는 약함.
  • GraphQL: 데이터 최적화/유연성/타입 안전 강점. 캐시·보안·관찰성 설계가 필수.