정의
GraphQL은 Meta(구 페이스북)가 2012년에 내부용으로 개발하고 2015년에 오픈소스로 공개한 API 쿼리 언어이자 런타임입니다. 클라이언트(프론트엔드, 앱, 커머스 프론트)가 필요한 데이터의 구조를 직접 정의해서 요청하면, 서버는 그 구조에 정확히 맞는 JSON만 돌려줍니다. REST API처럼 여러 엔드포인트를 오가며 데이터를 조립할 필요 없이, 단 하나의 엔드포인트(/graphql)에서 원하는 필드만 골라 받는 방식입니다. Headless 커머스 아키텍처에서 Shopify, Magento, Saleor, Commercetools 같은 플랫폼이 기본 API로 GraphQL을 채택하면서 DTC 업계의 표준으로 자리 잡았습니다.
비유로 이해하기
REST API가 정해진 코스 요리라면, GraphQL은 뷔페입니다. 코스 요리는 셰프가 정한 순서와 양대로 나오기 때문에 안 먹는 반찬도 접시에 올라옵니다(Over-fetching). 반면 뷔페에서는 내가 먹고 싶은 것만, 먹고 싶은 만큼 담습니다. DTC 관점에서 보면 이 차이는 곧 모바일 트래픽과 페이지 로딩 속도입니다. 상품 상세 페이지에서 썸네일 1장, 가격, 재고만 필요한데 REST가 리뷰 20개, 관련 상품 10개, 사이즈 차트까지 다 내려준다면 그만큼 데이터 요금과 렌더링 시간이 낭비됩니다.
공식
GraphQL의 요청-응답 효율은 다음처럼 정량화할 수 있습니다.
전송 데이터량 = Σ(요청 필드 × 평균 페이로드) 절감률 = (REST 응답 크기 − GraphQL 응답 크기) / REST 응답 크기 × 100
예시:
- REST 상품 API 응답: 48KB (리뷰, 추천, 메타데이터 포함)
- GraphQL 동일 목적 쿼리 응답: 11KB (name, price, stock, thumbnail만)
- 절감률 = (48 − 11) / 48 × 100 = 77.1%
쿼리 복잡도는 아래처럼 제한을 두는 것이 일반적입니다.
쿼리 비용 = Σ(필드 가중치 × 요청 개수) Rate Limit 예: 초당 1,000 포인트, 단일 쿼리 최대 300 포인트
REST vs GraphQL 비교
| 항목 | REST API | GraphQL |
|---|---|---|
| 엔드포인트 | 리소스별 다수 (`/products`, `/orders`) | 단일 (`/graphql`) |
| 데이터 과다 수신 | 발생 (Over-fetching) | 요청 필드만 수신 |
| 데이터 부족 | 다중 호출 필요 (Under-fetching) | 1회 쿼리로 해결 |
| 버전 관리 | `/v1`, `/v2` 경로 분기 | 스키마 진화 (Deprecation) |
| 캐싱 | HTTP 캐시 자연 지원 | Persisted Query, CDN 캐시 별도 구성 |
| 학습 곡선 | 낮음 | 중~높음 (스키마, 리졸버) |
| DTC 적합성 | 단순 카탈로그 | Headless, 다채널, 모바일 |
DTC/커머스 적용 시나리오
1. Headless 스토어프론트: Next.js + Shopify Storefront API(GraphQL) 조합. PDP에서 상품, 변형(variant), 재고, 가격을 한 번에 가져와 LCP 1.8초 달성 사례 다수.
2. 다채널 동기화: 자사몰, 앱, 마켓플레이스가 동일 GraphQL 스키마를 공유. 신규 채널 추가 시 백엔드 수정 없이 프론트만 붙이면 됩니다.
3. 개인화 추천: 사용자 ID 기반으로 추천 상품 3개, 최근 본 상품 5개를 단일 쿼리로 요청. REST 대비 호출 횟수 6회 → 1회.
4. 실시간 재고/프로모션: 장바구니 단계에서 프로모션 코드, 배송비, 예상 도착일을 한 쿼리로 계산.
5. 어드민 대시보드: 주문, 반품, CS 데이터를 필요한 지표만 조합해 조회.
흔한 오해
- "GraphQL이면 무조건 빠르다" → 아닙니다. 리졸버에서 N+1 쿼리가 발생하면 REST보다 느려집니다. DataLoader 같은 배칭이 필수입니다.
- "REST를 완전히 대체한다" → 파일 업로드, 웹훅, 단순 정적 리소스는 REST가 여전히 유리합니다. 하이브리드가 현실적입니다.
- "캐싱이 자동이다" → HTTP 상태 코드 기반 캐싱이 없어 Persisted Query, Apollo Cache, CDN 규칙을 직접 설계해야 합니다.
- "스키마만 짜면 끝" → 권한, Rate Limit, 쿼리 깊이 제한, 에러 포맷 설계가 운영의 핵심입니다.
- "작은 스토어에는 과하다" → 상품 100개 이하, 단일 채널이면 REST나 플랫폼 기본 API로 충분합니다.
관련 용어
- REST API: 리소스 기반 전통적 API 설계
- Headless Commerce: 프론트와 백엔드 분리형 커머스 구조
- Storefront API: Shopify 등이 제공하는 커머스 특화 GraphQL 엔드포인트
- Resolver: 스키마 필드를 실제 데이터로 채우는 함수
- DataLoader: N+1 문제를 해결하는 배칭/캐싱 유틸
- Persisted Query: 쿼리를 해시로 저장해 전송량을 줄이는 기법
- Schema Stitching / Federation: 여러 GraphQL 서비스를 하나로 통합
- Apollo Client / urql: 대표적인 GraphQL 클라이언트 라이브러리
