정의
REST API는 HTTP 프로토콜을 기반으로 시스템 간 데이터를 주고받는 표준화된 인터페이스 설계 방식입니다. 엄밀히 말하면 REST는 “아키텍처 스타일”이고, 이를 실제로 구현한 것이 REST API입니다.
DTC·이커머스 실무에서는 주문(Order), 재고(Inventory), 광고 성과(Ad Spends), 물류(Tracking) 데이터를 외부 시스템과 동기화할 때 사실상의 표준으로 쓰입니다. Shopify Admin API, Meta Marketing API, Cafe24 Open API, 카카오 알림톡 발송 API 등이 모두 REST 방식입니다.
핵심 원칙은 다음과 같습니다.
- 자원(Resource)은 URI로 표현: /orders/1001
- 행위는 HTTP 메서드로 표현: GET, POST, PUT, PATCH, DELETE
- 무상태성(Stateless): 각 요청은 독립적이며 서버가 이전 요청을 기억하지 않음
- 표현(Representation): 응답은 JSON이 기본 (가끔 XML)
비유로 이해하기
REST API는 “식당의 정해진 주문서 양식” 과 같습니다.
- 메뉴판 = 엔드포인트 목록 (GET /products)
- 주문서 양식 = HTTP 메서드 (조회는 GET, 신규는 POST)
- 주문 번호 = 리소스 ID (/orders/1001)
- 주방 = 백엔드 서버
웨이터(API)에게 “3번 테이블 주문서에 ‘김치찌개 2개 추가’라고 적어주세요”라고 하면, 주방에서는 그 양식대로 처리합니다. 양식이 통일되어 있으니 어떤 웨이터가 받아도 동일하게 처리됩니다. 이게 REST의 힘입니다.
공식 & 구조
REST 호출의 기본 구조는 다음과 같습니다.
METHOD /resource/{id}?query=value
Headers: Authorization, Content-Type
Body: { "key": "value" }
실제 DTC 주문 동기화 예시:
GET /admin/api/2024-10/orders.json?status=any&limit=250 Header: X-Shopify-Access-Token: shpat_xxxxx
처리량 계산 공식 (레이트 리밋 대응):
필요 호출 수 = 전체 데이터 수 ÷ 페이지당 건수 소요 시간(초) = 필요 호출 수 ÷ 초당 허용 호출 수
예시: 주문 50,000건, 페이지당 250건, 초당 2회 제한
- 필요 호출 수 = 50,000 ÷ 250 = 200회
- 소요 시간 = 200 ÷ 2 = 100초 (약 1분 40초)
리트라이 백오프 공식 (지수 백오프):
대기 시간 = base × 2^attempt
base=1초, attempt=3이면 → 1 × 2³ = 8초 대기 후 재시도
REST vs GraphQL vs SOAP 비교
| 항목 | REST API | GraphQL | SOAP |
|---|---|---|---|
| 전송 방식 | HTTP | HTTP | HTTP/SMTP |
| 데이터 형식 | JSON | JSON | XML |
| 엔드포인트 | 다수 (리소스별) | 단일 | 단일 |
| 오버페칭 | 발생 | 없음 | 심함 |
| 학습 난이도 | 낮음 | 중간 | 높음 |
| DTC 활용도 | ★★★★★ | ★★★★ | ★ |
| 대표 사례 | Shopify, Meta Ads | Shopify Storefront | 레거시 ERP |
DTC 실무에서는 REST가 90% 이상, GraphQL은 스토어프론트 영역에서 병행 사용됩니다.
DTC·이커머스 적용 시나리오
1. 주문 동기화 (Order Sync)
쇼피파이 → 자사 ERP로 주문 5,000건/일 전송.
- GET /orders.json?updated_at_min=2024-10-01
- 평균 응답 200ms, 하루 20회 폴링
2. 재고 실시간 반영 (Inventory Sync)
3개 판매 채널(자사몰, 스마트스토어, 쿠팡) 재고를 5분 주기로 동기화.
- PUT /inventory_levels/set.json
- SKU 12,000개 × 288회/일 = 약 345만 호출/월
3. 광고 성과 수집 (Ad Performance)
Meta Marketing API로 캠페인 300개 지표 수집.
- GET /v20.0/act_{id}/insights?level=campaign
- 일 1회, ROAS 계산 후 대시보드 반영
4. 물류 추적 (Tracking)
CJ대한통운 API로 운송장 8,000건 상태 조회.
- GET /tracking/{invoiceNo}
자주 하는 오해 & 실수
① “REST는 GET/POST만 쓰면 된다”
→ PUT, PATCH, DELETE를 적절히 써야 합니다. PATCH는 부분 수정, PUT은 전체 교체입니다. 이걸 혼동하면 재고가 0으로 덮어써지는 사고가 납니다.
② “무상태니까 세션 없이 아무 때나 호출 가능”
→ 무상태는 서버가 상태를 저장하지 않는다는 뜻이지, 인증 토큰이 불필요하다는 뜻이 아닙니다. OAuth 2.0 토큰은 매 요청 헤더에 포함해야 합니다.
③ “레이트 리밋은 넉넉하다”
→ Shopify REST는 초당 2회(앱당), Meta Ads는 시간당 200회 수준입니다. 5,000건 주문을 1초에 밀어넣으려다 429 Too Many Requests 폭탄을 맞습니다.
④ “에러는 200 OK면 성공”
→ 200이어도 body에 "errors": [...]가 들어올 수 있습니다. 반드시 응답 본문을 파싱해야 합니다.
⑤ “페이지네이션 무시”
→ limit만 걸고 cursor를 안 넘기면 첫 250건만 계속 받습니다. Link 헤더의 rel="next"를 반드시 따라가야 합니다.
⑥ “웹훅이면 REST 불필요”
→ 웹훅은 이벤트 알림일 뿐, 과거 데이터 백필은 REST로 해야 합니다.
관련 용어
- Endpoint: API가 노출하는 접근 주소 (/orders)
- Payload: 요청/응답 본문 (JSON)
- Rate Limit: 단위 시간당 호출 제한
- Webhook: 서버 → 클라이언트 푸시 알림
- OAuth 2.0: REST API 인증 표준
- Idempotency Key: 중복 요청 방지 키 (결제·주문 생성 시 필수)
- GraphQL: REST의 대안, 단일 엔드포인트
- gRPC: 초고속 바이너리 프로토콜, 내부 MSA 통신용
- Pagination / Cursor: 대량 데이터 분할 조회
- 429 Error: 레이트 리밋 초과 응답 코드
마무리
REST API는 DTC 커머스의 혈관입니다. 주문·재고·광고·물류가 모두 이 혈관을 타고 흐릅니다. 속도(레이트 리밋), 정확성(멱등성), 안정성(리트라이) 세 가지를 놓치면 새벽 3시에 재고가 마이너스로 찍히는 알람을 받게 됩니다. 설계 단계에서 “이 호출이 실패하면 어떻게 복구할까” 를 먼저 생각하는 팀이 결국 이깁니다.
