Zonos는 통합을 위해 GraphQL과 REST라는 두 가지 주요 API를 제공합니다. REST API는 더 오래전부터 사용되어 많은 분들에게 익숙할 수 있지만, Zonos는 더 큰 유연성과 빠른 혁신을 위해 GraphQL로 전환했습니다. 두 API를 모두 계속 지원하지만, 이 가이드에서는 GraphQL이 Zonos 통합의 미래일 뿐 아니라 통합 전반의 미래이며, 오늘날의 필요를 충족하는 더 강력한 도구인 이유를 설명합니다.
GraphQL은 API와 통신하는 또 다른 방식으로, 복잡한 데이터 구조와 그 위에 인터페이스를 구축하는 데 매우 적합합니다. 데이터를 서로 분리된 독립적인 조각으로 다루는 대신, GraphQL은 데이터 조각들이 어떻게 연결되고 관계를 맺는지 보여주어 정보를 요청하고 받기 쉽게 만들어줍니다.
GraphQL을 데이터베이스에 직접 이야기하듯 API와 통신할 수 있게 해주는 쿼리 언어라고 생각하면 됩니다. GraphQL을 사용하면 데이터베이스에 최대한 가깝게 접근하여 원하는 데이터와 그 수신 방식을 직접 선택할 수 있으므로 성능 측면에서 큰 이점을 얻을 수 있습니다.
GraphQL은 Facebook이 복잡한 데이터 구조를 확장하는 문제를 해결하기 위해 만들었습니다. Facebook이 이를 성공적으로 도입한 이후, 점점 더 많은 기업이 자사 API에 GraphQL을 사용하는 것의 이점을 깨닫고 있습니다.
이미 REST를 알고 있다면 GraphQL도 낯설지 않을 것입니다
GraphQL API는 생각보다 다루기 쉽습니다. REST API에 익숙하다면, REST의 핵심 개념이 GraphQL에서 어떻게 대응되는지 아래에서 확인해보세요.
기능↕
REST↕
GraphQL↕
엔드포인트
작업마다 서로 다른 여러 엔드포인트에 요청을 보냅니다
모든 요청이 단일 엔드포인트(예: /graphql)로 전송됩니다
데이터 조회
특정 엔드포인트에서 GET 메서드로 데이터를 조회합니다
쿼리를 사용해 필요한 데이터만 정확히 요청하여 과다·과소 조회를 줄입니다
데이터 수정/작업
POST, PUT, PATCH, DELETE 같은 HTTP 메서드로 데이터를 수정하거나 처리합니다.
뮤테이션을 사용해 작업을 수행합니다(예: 파티 생성, landed cost 계산)
응답 형식
필요 여부와 관계없이 미리 정의된 모든 필드를 반환하는 고정된 응답 형식입니다
포함할 필드를 정확히 지정할 수 있는 유연한 응답으로 불필요한 데이터 전송을 줄입니다(이러한 유연성이 복잡하게 느껴진다면, 문서에 미리 작성된 쿼리 예제를 그대로 사용해 RESTful한 경험을 얻을 수 있습니다)
데이터 연결
관련 데이터를 가져오려면 여러 번 요청해야 하는 경우가 많습니다
중첩 쿼리를 사용하면 단일 요청으로 관련 데이터를 함께 조회할 수 있습니다(예: 파티 정보와 배송 항목을 함께 조회). 또한 단일 GraphQL 요청 내에서 여러 뮤테이션을 관리하는 워크플로를 구성해 복잡성을 줄이고 효율성을 높일 수 있습니다
GraphQL의 장점
더 빠른 응답
GraphQL은 정밀한 데이터 조회, 단일 엔드포인트 사용, 배칭 및 캐싱 기능 개선을 통해 더 빠른 응답을 제공합니다.
정밀한 데이터 조회
REST의 흔한 문제는 데이터를 과다하게 조회하거나 부족하게 조회하는 것입니다. 즉, 한 번에 불필요한 정보를 너무 많이 받거나 필요한 정보를 충분히 받지 못하는 것입니다. GraphQL은 필요한 것만 정확히 요청할 수 있게 해줌으로써 이 문제를 없애줍니다—더도 덜도 아닌 필요한 만큼만 말입니다. 이러한 정밀함은 성능을 개선할 뿐만 아니라 API를 사용하는 사람들의 작업 과정을 단순화하여 시스템을 더 효율적이고 사용하기 쉽게 만들어줍니다.
유용한 예:
이를 통해 프런트엔드 개발자는 UI 컴포넌트에 필요한 데이터만 정확히 가져올 수 있어 서버로의 왕복 요청 수를 줄이고 성능을 개선할 수 있습니다.
체크아웃에 담긴 상품에 대해 HS 코드 분류, 카톤화(cartonization), 배송 요율, landed cost 견적을 받아야 한다고 가정해 보세요. GraphQL API로 통합했다면 필요한 워크플로를 사용해 단 한 번의 호출로 필요한 모든 것(그리고 필요하지 않은 것은 제외한)을 단일 응답으로 받을 수 있습니다. 반면 REST API를 사용하면 먼저 Classify REST API를 호출한 다음 별도로 Rating REST API를 호출하고, 마지막으로 그 분류와 배송 요율 결과를 세 번째 호출인 Landed Cost REST API에 입력해야 합니다. 이러한 REST API는 모두 가능한 모든 정보를 반환하므로 필요한 데이터를 얻기 위해 응답을 일일이 파싱해야 합니다. 이러한 속도 절감은 쇼핑객이 이탈하기 전에 완전한 landed cost를 빠르게 반환하는 데 큰 영향을 줍니다.
단일 엔드포인트
GraphQL API는 일반적으로 단일 엔드포인트를 가지는 반면, REST API는 리소스와 작업마다 여러 엔드포인트를 갖는 경우가 많습니다. 이는 API를 관리하고 이해하기 더 단순하게 만들어줍니다.
배칭 및 캐싱
GraphQL은 쿼리를 배칭하는 기능과 캐싱 전략을 지원하여 상당한 성능 개선을 이끌어냅니다. 이러한 기능은 네트워크와 서버의 부하를 줄여 사용자에게 더 빠르고 안정적인 상호작용을 제공합니다.
명확하게 정의된 스키마
GraphQL API는 강타입(strongly typed) 스키마를 기반으로 합니다. 이 스키마는 사용 가능한 데이터의 구조와 수행할 수 있는 작업을 정의합니다. 이를 통해 어떤 데이터를 사용할 수 있고 어떻게 접근하는지가 명확해져 개발자의 생산성을 높이고 오류를 줄일 수 있습니다. 예를 들어 프런트엔드 팀은 새로운 REST 엔드포인트를 기다리지 않고도 그래프를 탐색하여 필요한 것을 정확히 얻을 수 있습니다.
기존 클라이언트를 깨뜨리지 않고 개선하는 능력
GraphQL은 유연한 쿼리 구조 덕분에 새 기능을 추가하거나 기존 기능을 수정해도 현재 통합에 영향을 주지 않습니다. 이 기능 덕분에 기존 클라이언트와의 호환성을 깨뜨리지 않고도 개선을 진행할 수 있습니다.
최신 상태로 유지되는 문서
GraphQL의 인트로스펙션(introspection) 기능 덕분에 문서는 변경 사항이 있을 때마다 자동으로 생성되고 업데이트됩니다. 이를 통해 개발자에게 제공되는 모든 정보가 항상 최신 상태로 유지되어, 오래된 문서로 인한 통합 문제와 지원 티켓을 줄일 수 있습니다—이는 REST API 문서에서 흔히 겪는 문제입니다.
원하는 대로 요리를 주문할 수 있는 메뉴가 있는 레스토랑과, 정해진 세트 메뉴만 고를 수 있는 또 다른 레스토랑을 비교한다고 생각해 보세요. GraphQL은 첫 번째 레스토랑과 같습니다:
정확히 원하는 것만 얻기: GraphQL을 사용하면 필요한 데이터만 정확히 요청할 수 있습니다—더도 덜도 아닙니다. 요리의 이름과 가격만 원하고 전체 재료 목록은 필요 없다고 가정해 보세요. REST API를 사용하면 요리에 대한 전체 정보를 받은 뒤 필요 없는 부분을 무시해야 합니다.
맞춤 요리 구성하기: Zonos의 GraphQL API는 쉽게 조합하여 더 맞춤화된 솔루션을 만들 수 있습니다. 이미 준비된 재료로 원하는 대로 유일무이한 요리를 만들 수 있는 뷔페식 레스토랑과 비슷합니다. 반면 REST API는 바구니에 미리 포장된 완제품을 파는 베이커리와 같아서, 이미 만들어진 것만 주문할 수 있고 원하는 부분만 골라서 가져갈 수는 없습니다.
대기 시간 줄이기: 필요한 모든 정보를 단 한 번의 요청으로 받을 수 있으므로, 코스 사이에 기다리는 대신 애피타이저, 메인 코스, 디저트를 한 번에 가져다 달라고 요청하는 것과 같습니다. 대부분의 REST API는 서로 다른 정보를 얻기 위해 여러 번 요청을 보내야 합니다.
주문 변경이 쉬움: 앱의 데이터 요구 사항이 바뀌면 GraphQL로 더 쉽게 조정할 수 있습니다. 필요한 것에 맞춰 쿼리만 바꾸면 됩니다. REST를 사용하면 주방(백엔드)이 메뉴에 새로운 요리(엔드포인트)를 만들어 줄 때까지 기다려야 할 수 있으며, 이는 더 많은 시간이 걸립니다.
GraphQL은 특히 요구 사항이 변화하고 확장될 때 REST API보다 데이터를 가져오는 데 있어 더 큰 유연성, 효율성, 단순함을 제공합니다.
지난 몇 년간 플랫폼을 현대화하는 과정에서 Zonos는 API의 새로운 기능을 REST 대신 GraphQL로 구축하기로 결정했습니다. Zonos의 데이터가 Facebook이 GraphQL을 만들게 된 데이터와 마찬가지로 복잡하고 상호 연결되어 있기 때문입니다. 이러한 복잡성 때문에 확장 가능한 REST API를 구축하기가 어려운데, 개발자가 데이터를 가져오고 사용하는 방식이 구현마다 크게 달라지는 반면 REST는 유연하지 않기 때문입니다.
GraphQL은 API를 구현하는 개발자가 원하는 데이터와 그 수신 방식을 정확히 선택할 수 있게 하여 이 문제를 깔끔하게 해결합니다. 이를 통해 개발자는 매번 Zonos가 별도의 맞춤 작업을 해주기를 기다릴 필요 없이 자신의 워크플로에 맞게 API를 활용할 수 있습니다.
GraphQL 사용과 플랫폼 현대화가 결합된 결과, Zonos의 API는 더 높은 성능을 갖게 되었고, Zonos를 시스템에 통합하는 과정이 더 빨라졌으며, Zonos가 새로운 기능을 더 빠르게 제공할 수 있게 되었습니다.
더 나은 기능
Zonos는 새로운 기능을 지속적으로 개발하며, GraphQL이 이러한 업데이트를 가장 먼저(그리고 대부분 유일하게) 받습니다. 반면 Zonos의 REST API는 수명 종료(end-of-life) 상태로 간주되어 많은 신규 기능에 접근할 수 없습니다.
GraphQL에서만 사용할 수 있는 기능 예시:
Inclusive pricing
Labels API
새로운 Checkout 및 Hello
API 응답의 박스 크기 정보
Dashboard 리포팅
가능한 경우 DDP 견적을 요청하고, 해당 국가·서비스 레벨에서 DDP를 사용할 수 없으면 DDU 견적을 반환하는 기능
관세, 세금, 수수료의 상세 내역(품목 단위 정보, 세부 수수료)—Dashboard는 GraphQL로 구동되어 모든 스토어에 이 데이터를 표시하지만, REST API 응답에는 이 수준의 세부 정보가 포함되지 않습니다
GraphQL을 사용하는 이유
GraphQL을 사용하는 이유
REST보다 GraphQL을 통한 통합을 권장하는 이유를 알아보세요.
Zonos는 통합을 위해 GraphQL과 REST라는 두 가지 주요 API를 제공합니다. REST API는 더 오래전부터 사용되어 많은 분들에게 익숙할 수 있지만, Zonos는 더 큰 유연성과 빠른 혁신을 위해 GraphQL로 전환했습니다. 두 API를 모두 계속 지원하지만, 이 가이드에서는 GraphQL이 Zonos 통합의 미래일 뿐 아니라 통합 전반의 미래이며, 오늘날의 필요를 충족하는 더 강력한 도구인 이유를 설명합니다.
GraphQL이란?
GraphQL은 API와 통신하는 또 다른 방식으로, 복잡한 데이터 구조와 그 위에 인터페이스를 구축하는 데 매우 적합합니다. 데이터를 서로 분리된 독립적인 조각으로 다루는 대신, GraphQL은 데이터 조각들이 어떻게 연결되고 관계를 맺는지 보여주어 정보를 요청하고 받기 쉽게 만들어줍니다.
GraphQL을 데이터베이스에 직접 이야기하듯 API와 통신할 수 있게 해주는 쿼리 언어라고 생각하면 됩니다. GraphQL을 사용하면 데이터베이스에 최대한 가깝게 접근하여 원하는 데이터와 그 수신 방식을 직접 선택할 수 있으므로 성능 측면에서 큰 이점을 얻을 수 있습니다.
GraphQL은 Facebook이 복잡한 데이터 구조를 확장하는 문제를 해결하기 위해 만들었습니다. Facebook이 이를 성공적으로 도입한 이후, 점점 더 많은 기업이 자사 API에 GraphQL을 사용하는 것의 이점을 깨닫고 있습니다.
이미 REST를 알고 있다면 GraphQL도 낯설지 않을 것입니다
GraphQL API는 생각보다 다루기 쉽습니다. REST API에 익숙하다면, REST의 핵심 개념이 GraphQL에서 어떻게 대응되는지 아래에서 확인해보세요.
GraphQL의 장점
더 빠른 응답
GraphQL은 정밀한 데이터 조회, 단일 엔드포인트 사용, 배칭 및 캐싱 기능 개선을 통해 더 빠른 응답을 제공합니다.
정밀한 데이터 조회
REST의 흔한 문제는 데이터를 과다하게 조회하거나 부족하게 조회하는 것입니다. 즉, 한 번에 불필요한 정보를 너무 많이 받거나 필요한 정보를 충분히 받지 못하는 것입니다. GraphQL은 필요한 것만 정확히 요청할 수 있게 해줌으로써 이 문제를 없애줍니다—더도 덜도 아닌 필요한 만큼만 말입니다. 이러한 정밀함은 성능을 개선할 뿐만 아니라 API를 사용하는 사람들의 작업 과정을 단순화하여 시스템을 더 효율적이고 사용하기 쉽게 만들어줍니다.
유용한 예:
단일 엔드포인트
GraphQL API는 일반적으로 단일 엔드포인트를 가지는 반면, REST API는 리소스와 작업마다 여러 엔드포인트를 갖는 경우가 많습니다. 이는 API를 관리하고 이해하기 더 단순하게 만들어줍니다.
배칭 및 캐싱
GraphQL은 쿼리를 배칭하는 기능과 캐싱 전략을 지원하여 상당한 성능 개선을 이끌어냅니다. 이러한 기능은 네트워크와 서버의 부하를 줄여 사용자에게 더 빠르고 안정적인 상호작용을 제공합니다.
명확하게 정의된 스키마
GraphQL API는 강타입(strongly typed) 스키마를 기반으로 합니다. 이 스키마는 사용 가능한 데이터의 구조와 수행할 수 있는 작업을 정의합니다. 이를 통해 어떤 데이터를 사용할 수 있고 어떻게 접근하는지가 명확해져 개발자의 생산성을 높이고 오류를 줄일 수 있습니다. 예를 들어 프런트엔드 팀은 새로운 REST 엔드포인트를 기다리지 않고도 그래프를 탐색하여 필요한 것을 정확히 얻을 수 있습니다.
기존 클라이언트를 깨뜨리지 않고 개선하는 능력
GraphQL은 유연한 쿼리 구조 덕분에 새 기능을 추가하거나 기존 기능을 수정해도 현재 통합에 영향을 주지 않습니다. 이 기능 덕분에 기존 클라이언트와의 호환성을 깨뜨리지 않고도 개선을 진행할 수 있습니다.
최신 상태로 유지되는 문서
GraphQL의 인트로스펙션(introspection) 기능 덕분에 문서는 변경 사항이 있을 때마다 자동으로 생성되고 업데이트됩니다. 이를 통해 개발자에게 제공되는 모든 정보가 항상 최신 상태로 유지되어, 오래된 문서로 인한 통합 문제와 지원 티켓을 줄일 수 있습니다—이는 REST API 문서에서 흔히 겪는 문제입니다.
차이를 직접 확인하려면 GraphQL 문서와 REST 문서를 살펴보세요.
비유
원하는 대로 요리를 주문할 수 있는 메뉴가 있는 레스토랑과, 정해진 세트 메뉴만 고를 수 있는 또 다른 레스토랑을 비교한다고 생각해 보세요. GraphQL은 첫 번째 레스토랑과 같습니다:
GraphQL은 특히 요구 사항이 변화하고 확장될 때 REST API보다 데이터를 가져오는 데 있어 더 큰 유연성, 효율성, 단순함을 제공합니다.
Zonos가 GraphQL을 사용하는 방식
지난 몇 년간 플랫폼을 현대화하는 과정에서 Zonos는 API의 새로운 기능을 REST 대신 GraphQL로 구축하기로 결정했습니다. Zonos의 데이터가 Facebook이 GraphQL을 만들게 된 데이터와 마찬가지로 복잡하고 상호 연결되어 있기 때문입니다. 이러한 복잡성 때문에 확장 가능한 REST API를 구축하기가 어려운데, 개발자가 데이터를 가져오고 사용하는 방식이 구현마다 크게 달라지는 반면 REST는 유연하지 않기 때문입니다.
GraphQL은 API를 구현하는 개발자가 원하는 데이터와 그 수신 방식을 정확히 선택할 수 있게 하여 이 문제를 깔끔하게 해결합니다. 이를 통해 개발자는 매번 Zonos가 별도의 맞춤 작업을 해주기를 기다릴 필요 없이 자신의 워크플로에 맞게 API를 활용할 수 있습니다.
GraphQL 사용과 플랫폼 현대화가 결합된 결과, Zonos의 API는 더 높은 성능을 갖게 되었고, Zonos를 시스템에 통합하는 과정이 더 빨라졌으며, Zonos가 새로운 기능을 더 빠르게 제공할 수 있게 되었습니다.
더 나은 기능
Zonos는 새로운 기능을 지속적으로 개발하며, GraphQL이 이러한 업데이트를 가장 먼저(그리고 대부분 유일하게) 받습니다. 반면 Zonos의 REST API는 수명 종료(end-of-life) 상태로 간주되어 많은 신규 기능에 접근할 수 없습니다.
GraphQL에서만 사용할 수 있는 기능 예시:
이 페이지가 도움이 되었나요?