GraphQL이란?
GraphQL은 complex data structure와 그 위 interface 구축에 적합한 API 통신 방식입니다. data를 separate standalone piece로 다루지 않고 piece 간 연결·관계를 보여주어 information request와 수신이 쉽습니다.
GraphQL은 database에 직접 말하듯 API와 통신하는 query language로 생각하면 됩니다. GraphQL로 database에 최대한 가까워져 원하는 data와 수신 방식을 선택할 수 있어 큰 performance 이점이 있습니다.
GraphQL은 Facebook이 complex data structure scaling 문제를 해결하기 위해 만들었습니다. 성공적 adoption 이후 더 많은 company가 API에 GraphQL 사용 benefit을 깨닫고 있습니다.
REST를 알고 있다면 GraphQL도 익숙합니다.
GraphQL API는 생각보다 다루기 쉽습니다. REST API에 익숙하다면 REST의 핵심 개념이 GraphQL에서 어떻게 대응되는지 아래 표에서 확인할 수 있습니다.
| Feature↕ | REST↕ | GraphQL↕ |
|---|---|---|
| Endpoint | 다른 action마다 여러 endpoint에 request | 모든 request는 single endpoint(예: /graphql)에 전송 |
| Data retrieval | 특정 endpoint에서 GET method로 data 조회 | query로 필요한 data만 request하여 over-fetching·under-fetching 감소 |
| Data modification/actions | POST, PUT, PATCH, DELETE 등 HTTP method로 data 수정·처리 | mutation으로 operation 수행(예: party 생성, landed cost 계산) |
| Response format | predefined field를 모두 반환하는 고정 response format(필요 여부와 무관) | 포함할 field를 정확히 지정하는 flexible response로 불필요한 data transfer 감소(복잡하게 느껴지면 documentation의 pre-written query example을 사용하면 RESTful experience에 가깝습니다) |
| Data connection | related data fetch에 여러 request가 often 필요 | Nested query로 single request에서 related data 조회(예: party detail과 shipment item 함께). single GraphQL request에서 여러 mutation workflow도 구성 가능하여 complexity 감소·efficiency 향상 |
GraphQL 장점
더 빠른 response
GraphQL은 precise data retrieval, single endpoint 사용, batching·caching capability 향상으로 더 빠른 response를 제공합니다.
Precise data retrieval
REST의 common challenge는 over-fetching 또는 under-fetching입니다 — 불필요한 information이 너무 많거나 한 번에 필요한 것이 부족합니다. GraphQL은 필요한 것만 request하게 하여 이를 제거합니다. 이 specificity는 performance를 개선하고 API 사용자 process를 단순화하여 system을 더 efficient하고 user-friendly하게 만듭니다.
유용한 예:
- frontend developer가 UI component에 필요한 data만 fetch하여 server round trip을 줄이고 performance를 개선합니다.
- checkout item에 HS code classification, cartonization, shipment rating, landed cost quote가 필요하다고 가정합니다. GraphQL API 통합이면 필요한 workflow로 single call하여 single response에서 필요한 모든 것(불필요한 것 없이)을 받을 수 있습니다. REST API는 Classify REST API, Rating REST API, Landed Cost REST API를 순차 호출해야 하며 각 REST API는 가능한 모든 information을 반환하여 필요한 data를 parse해야 합니다. 이 speed savings는 shopper가 떠나기 전 complete landed cost를 빠르게 반환하는 데 영향을 줍니다.
Single endpoint
GraphQL API는 일반적으로 single endpoint를 갖고, REST API는 resource·action마다 여러 endpoint가 often 있습니다. API manage·이해가 더 simple합니다.
Batching 및 caching
GraphQL의 query batching capability와 caching strategy support는 significant performance improvement로 이어집니다. network·server load를 줄여 user에게 더 빠르고 reliable한 interaction을 제공합니다.
Well-defined schema
GraphQL API는 strongly typed schema 기반입니다. schema는 available data structure와 수행 가능 operation을 정의합니다. available data와 access 방법 clarity로 developer productivity 향상·error 감소에 도움이 됩니다. 예: frontend team이 새 REST endpoint를 기다리지 않고 graph를 explore하여 필요한 것을 정확히 얻을 수 있습니다.
Existing client를 깨뜨리지 않고 개선
GraphQL의 flexible query structure 덕분에 feature 추가·기존 feature 수정이 current integration을 disrupt하지 않습니다. existing client compatibility를 깨뜨리지 않고 improvement가 가능합니다.
Up-to-date documentation
GraphQL introspection feature로 documentation이 change마다 자동 생성·업데이트됩니다. developer에게 제공되는 information이 current하여 integration issue와 outdated documentation 관련 support ticket을 줄입니다 — REST API documentation에서 common challenge입니다.
GraphQL documentation과 REST documentation을 비교해 차이를 확인하세요.
비유
원하는 대로 dish를 주문할 수 있는 menu restaurant과 set meal만 선택하는 restaurant를 비유합니다. GraphQL은 첫 번째 restaurant와 같습니다:
- 정확히 원하는 것만: GraphQL로 필요한 data만 request합니다. dish name과 price만 원하고 ingredient list 전체는 원하지 않는 경우를 생각하세요. REST API는 entire dish detail을 받고 불필요한 부분을 ignore해야 합니다.
- Custom dish 구성: GraphQL API는 쉽게 결합하여 custom solution을 만들 수 있습니다 — buffet-style restaurant처럼已有 ingredient로 필요한 one-of-a-kind dish를 만듭니다. REST API는 pre-made goods basket bakery와 같아 이미 만들어진 것만 order하고 원하는 piece만 가져갈 수 없습니다.
- 대기 시간 감소: single request로 필요한 모든 information을 받을 수 있어 appetizer, main course, dessert를 한 번에 받는 것과 같습니다. 대부분 REST API는 다른 information piece마다 여러 request가 필요합니다.
- Order 변경 용이: app data needs가 바뀌면 GraphQL로 쉽게 adjust합니다. 필요한 query만 변경하면 됩니다. REST는 kitchen(backend)이 새 meal(endpoint)을 menu에 만들 때까지 기다려야 할 수 있습니다.
GraphQL은 needs가 change·grow할 때 특히 REST API보다 data fetch에 더 많은 flexibility, efficiency, simplicity를 제공합니다.
Zonos의 GraphQL 사용
지난 몇 년 platform modernization 중 Zonos는 REST 대신 GraphQL로 새 functionality를 구축하기로 했습니다. data가 complex하고 interconnected하여 Facebook이 GraphQL을 만든 data와 유사하기 때문입니다. developer가 data를 fetch·사용하는 방식이 implementation마다 dramatically 다르고 REST는 flexible하지 않아 scalable REST API 구축이 challenging합니다.
GraphQL은 API를 implement하는 developer가 원하는 data와 수신 방식을 정확히 선택하게 하여 이 problem을 neatly 해결합니다. every situation마다 Zonos custom work(대기) 없이 workflow에 맞출 수 있습니다.
GraphQL 사용과 platform modernization의 combined result로 API가 더 performant해졌고, system 통합이 faster해졌으며, Zonos가 새 feature를 더 quickly deliver할 수 있게 되었습니다.
더 나은 feature
Zonos는 지속적으로 새 feature를 개발하며 GraphQL이 first(그리고 usually only) update를 받습니다. REST API는 end-of-life로 many new feature에 access할 수 없습니다.
GraphQL로만 제한된 feature 예:
- Inclusive pricing
- Labels API
- New Checkout and Hello
- API response의 box size
- Dashboard reporting
- 가능하면 DDP quote request, 해당 country·service level에서 DDP unavailable 시 DDU quote 반환
- Duty, tax, fee 상세 breakdown(item-level information, specific fee) — Dashboard는 GraphQL powered로 모든 store에 이 data 표시, REST API response에는 이 detail level 없음
- Test mode(출시 예정)
Why GraphQL
REST보다 GraphQL 통합을 권장하는 이유를 알아봅니다.
Zonos는 통합용 GraphQL과 REST 두 가지 API를 제공합니다. REST API가 더 오래되었고 익숙할 수 있지만, 더 많은 flexibility와 빠른 innovation을 위해 GraphQL로 전환했습니다. 둘 다 지원하지만 이 가이드는 GraphQL이 integration의 미래이자 오늘 needs를 충족하는 더 강력한 tool인 이유를 설명합니다.