Узнайте, почему мы рекомендуем интеграцию через GraphQL вместо REST.
В Zonos мы предлагаем два основных типа API для интеграции: GraphQL и REST. Хотя REST API существует дольше и может быть более знаком многим, мы перешли на GraphQL, чтобы обеспечить большую гибкость и более быструю инновацию. Несмотря на то что оба варианта по-прежнему поддерживаются, это руководство объясняет, почему GraphQL не только является будущим наших интеграций, но и будущим интеграций в целом и более мощным инструментом для удовлетворения ваших потребностей сегодня.
GraphQL — это альтернативный способ взаимодействия с API, хорошо подходящий для сложных структур данных и создания на их основе интерфейсов. Вместо того чтобы рассматривать данные как отдельные, независимые элементы, GraphQL показывает, как части данных связаны и соотносятся между собой, облегчая запрос и получение информации.
Думайте о GraphQL как о языке запросов, который позволяет вам взаимодействовать с API так, как если бы вы разговаривали непосредственно с базой данных. Использование GraphQL позволяет вам подойти как можно ближе к базе данных, позволяя выбирать нужные вам данные и способ их получения, обеспечивая значительное преимущество в производительности.
GraphQL был создан Facebook для решения проблемы масштабирования со сложными структурами данных. В результате их успешного внедрения все больше и больше компаний начали понимать преимущества использования GraphQL для своих API.
Уже знакомы с REST? GraphQL покажется вам знакомым.
API GraphQL легче использовать, чем вы можете подумать. Если вы привыкли работать с REST API, вот как основные концепции из REST переводятся в GraphQL.
Функция↕
REST↕
GraphQL↕
Endpoint
Запросы отправляются на несколько разных endpoint для разных действий
Все запросы отправляются на один endpoint (например, /graphql)
Получение данных
Используйте методы GET на определённых endpoint для получения данных
Используйте запросы для запроса именно нужных вам данных, уменьшая чрезмерное или недостаточное получение
Изменение данных/действия
Используйте HTTP методы такие как POST, PUT, PATCH или DELETE для изменения или обработки данных.
Используйте мутации для выполнения операций (например, создание сторон, расчёт стоимости доставки)
Формат ответа
Фиксированные форматы ответов возвращают все предварительно определённые поля, независимо от того, нужны они или нет
Гибкие ответы позволяют указывать точно, какие поля включать, уменьшая ненужную передачу данных (если эта гибкость кажется сложной, просто используйте предварительно написанные примеры запросов в нашей документации для опыта, похожего на REST)
Связь данных
Часто требуется несколько запросов для получения связанных данных
Вложенные запросы позволяют получить связанные данные в одном запросе (например, детали стороны и элементы отправки вместе). Пользователи также могут создавать рабочие процессы для управления несколькими мутациями в одном запросе GraphQL, уменьшая сложность и повышая эффективность
Преимущества GraphQL
Более быстрые ответы
GraphQL обеспечивает более быстрые ответы через точное получение данных, использование одного endpoint и улучшенные возможности пакетной обработки и кэширования.
Точное получение данных
Распространённой проблемой REST является чрезмерное или недостаточное получение данных — либо получение слишком большого количества ненужной информации, либо недостаточного количества необходимого за один раз. GraphQL устраняет это, позволяя запрашивать ровно то, что нужно — ничего больше, ничего меньше. Эта специфичность не только улучшает производительность, но и упрощает процесс для тех, кто взаимодействует с API, делая систему более эффективной и удобной для пользователя.
Примеры того, как это полезно:
Это позволяет разработчикам фронтенда получить ровно те данные, которые им нужны для компонентов пользовательского интерфейса, уменьшая количество обращений к серверу и повышая производительность.
Представьте, что вы хотите получить классификацию кода HS, картонизацию, рейтинг отправки и расценку стоимости доставки на товары в корзине. Если вы интегрированы через GraphQL API, вы можете выполнить один вызов с необходимыми рабочими процессами для получения всего, что вам нужно (и ничего, что вам не нужно) в одном ответе. И наоборот, с REST API вам сначала нужно было бы вызвать Classify REST API, затем отдельно вызвать Rating REST API, и, наконец, подставить эту классификацию и рейтинг отправки в третий вызов Landed Cost REST API. Все эти REST API возвращали бы всю информацию, которую они могут, вынуждая вас разбирать ответ в поиске нужных данных. Эта экономия времени влияет на быстрое возвращение полной стоимости доставки до того, как покупатель уходит.
API GraphQL обычно имеют один endpoint, в отличие от REST API, которые часто имеют несколько endpoint для различных ресурсов и действий. Это упрощает управление и понимание API.
Пакетная обработка и кэширование
Способность GraphQL пакетировать запросы и его поддержка стратегий кэширования приводят к значительному улучшению производительности. Эти функции снижают нагрузку на сети и серверы, что приводит к более быстрому и надёжному взаимодействию для пользователей.
Хорошо определённые схемы
API GraphQL основаны на строго типизированной схеме. Эта схема определяет структуру доступных данных и операции, которые можно выполнять. Это обеспечивает ясность того, какие данные доступны и как к ним получить доступ, что может повысить производительность разработчиков и снизить ошибки. Например, фронтенд-команды могут исследовать граф, чтобы получить именно то, что им нужно, вместо ожидания нового REST endpoint.
Возможность улучшения без нарушения существующих клиентов
Добавление новых функций или изменение существующих в GraphQL не нарушает текущие интеграции благодаря его гибкой структуре запросов. Эта возможность гарантирует, что улучшения могут быть сделаны без нарушения совместимости с существующими клиентами.
Актуальная документация
Благодаря функции интроспекции GraphQL документация автоматически генерируется и обновляется с каждым изменением. Это гарантирует, что вся информация, предоставленная разработчикам, актуальна, уменьшая проблемы интеграции и запросы в поддержку, связанные с устаревшей документацией — проблема, которую часто испытывают с документацией REST API.
Представьте, что вы в ресторане с меню, которое позволяет вам заказывать блюда ровно так, как вы их хотите, по сравнению с другим рестораном, где вы можете выбрать только из установленных комплексов. GraphQL похож на первый ресторан:
Получите ровно то, что вам нужно: С GraphQL вы можете запросить ровно те данные, которые вам нужны, ни больше, ни меньше. Представьте, что вам нужно только имя и цена блюда, а не весь список ингредиентов. С REST API вам пришлось бы получить все детали блюда и игнорировать части, которые вам не нужны.
Составьте пользовательское блюдо: Наш GraphQL API можно легко комбинировать для создания более пользовательских решений, похожих на буфет, где вы можете создать уникальное блюдо ровно так, как вам нужно, используя ингредиенты, которые у них уже есть. И наоборот, REST API похож на пекарню с готовыми товарами в упакованных корзинах — вы можете заказать только то, что уже было создано, и вы не можете выбрать, чтобы взять домой только кусок, который вам нужен.
Меньше ожидания: Поскольку вы можете получить всю необходимую информацию в одном запросе, это похоже на то, что вы просите официанта принести ваши закуски, основное блюдо и десерт все сразу, вместо ожидания между блюдами. Большинство REST API требуют отправки нескольких запросов для получения различных фрагментов информации.
Легко менять заказы: Если потребности вашего приложения в данных изменятся, GraphQL упрощает корректировку. Вы просто меняете запрос на то, что вам нужно. С REST вам может потребоваться ждать, пока кухня (бэкенд) создаст новое блюдо (endpoint) для меню, что требует больше времени.
GraphQL предоставляет большую гибкость, эффективность и простоту для получения данных чем REST API, особенно при изменении или увеличении ваших потребностей.
При модернизации нашей платформы за последние пару лет Zonos решила разрабатывать новую функциональность на GraphQL для нашего API вместо REST. Мы решили сделать это потому, что наши данные сложны и взаимосвязаны, во многом как данные, которые привели Facebook к созданию GraphQL. Эта сложность усложняет создание масштабируемых REST API, потому что способы, которыми разработчикам нужно получать и использовать данные, варьируются кардинально между реализациями, а REST не гибкий.
GraphQL аккуратно решает эту проблему, позволяя разработчикам, реализующим наш API, выбирать ровно те данные, которые им нужны, и способ их получения. Это позволяет им вписаться в свои рабочие процессы без того, чтобы Zonos приходилось выполнять индивидуальную работу (пока они ждут) для каждой ситуации.
Комбинированный результат использования GraphQL и модернизаций в нашей платформе сделал наш API более производительным, сделал интеграцию Zonos в ваши системы быстрее и сделал возможным для Zonos быстрее доставлять новые функции.
Лучшие функции
Zonos постоянно разрабатывает новые функции, и GraphQL является первой (и обычно единственной) для получения этих обновлений. Напротив, наши REST API считаются устаревшими и не могут получить доступ ко многим нашим новым функциям.
Примеры функций, ограниченных GraphQL:
Inclusive pricing
Labels API
New Checkout и Hello
Размеры коробок в ответе API
Отчётность в Dashboard
Возможность запросить расценку DDP, если возможна, но по-прежнему вернуть расценку DDU, если DDP недоступна в этой стране с этим уровнем обслуживания
Детальная разбивка пошлин, налогов и сборов (информация на уровне товаров, специфические сборы) — Dashboard работает на GraphQL и показывает эти данные для всех магазинов, но ответ REST API не включает этот уровень детализации
Почему GraphQL
Почему GraphQL
Узнайте, почему мы рекомендуем интеграцию через GraphQL вместо REST.
В Zonos мы предлагаем два основных типа API для интеграции: GraphQL и REST. Хотя REST API существует дольше и может быть более знаком многим, мы перешли на GraphQL, чтобы обеспечить большую гибкость и более быструю инновацию. Несмотря на то что оба варианта по-прежнему поддерживаются, это руководство объясняет, почему GraphQL не только является будущим наших интеграций, но и будущим интеграций в целом и более мощным инструментом для удовлетворения ваших потребностей сегодня.
Что такое GraphQL?
GraphQL — это альтернативный способ взаимодействия с API, хорошо подходящий для сложных структур данных и создания на их основе интерфейсов. Вместо того чтобы рассматривать данные как отдельные, независимые элементы, GraphQL показывает, как части данных связаны и соотносятся между собой, облегчая запрос и получение информации.
Думайте о GraphQL как о языке запросов, который позволяет вам взаимодействовать с API так, как если бы вы разговаривали непосредственно с базой данных. Использование GraphQL позволяет вам подойти как можно ближе к базе данных, позволяя выбирать нужные вам данные и способ их получения, обеспечивая значительное преимущество в производительности.
GraphQL был создан Facebook для решения проблемы масштабирования со сложными структурами данных. В результате их успешного внедрения все больше и больше компаний начали понимать преимущества использования GraphQL для своих API.
Уже знакомы с REST? GraphQL покажется вам знакомым.
API GraphQL легче использовать, чем вы можете подумать. Если вы привыкли работать с REST API, вот как основные концепции из REST переводятся в GraphQL.
Преимущества GraphQL
Более быстрые ответы
GraphQL обеспечивает более быстрые ответы через точное получение данных, использование одного endpoint и улучшенные возможности пакетной обработки и кэширования.
Точное получение данных
Распространённой проблемой REST является чрезмерное или недостаточное получение данных — либо получение слишком большого количества ненужной информации, либо недостаточного количества необходимого за один раз. GraphQL устраняет это, позволяя запрашивать ровно то, что нужно — ничего больше, ничего меньше. Эта специфичность не только улучшает производительность, но и упрощает процесс для тех, кто взаимодействует с API, делая систему более эффективной и удобной для пользователя.
Примеры того, как это полезно:
Один endpoint
API GraphQL обычно имеют один endpoint, в отличие от REST API, которые часто имеют несколько endpoint для различных ресурсов и действий. Это упрощает управление и понимание API.
Пакетная обработка и кэширование
Способность GraphQL пакетировать запросы и его поддержка стратегий кэширования приводят к значительному улучшению производительности. Эти функции снижают нагрузку на сети и серверы, что приводит к более быстрому и надёжному взаимодействию для пользователей.
Хорошо определённые схемы
API GraphQL основаны на строго типизированной схеме. Эта схема определяет структуру доступных данных и операции, которые можно выполнять. Это обеспечивает ясность того, какие данные доступны и как к ним получить доступ, что может повысить производительность разработчиков и снизить ошибки. Например, фронтенд-команды могут исследовать граф, чтобы получить именно то, что им нужно, вместо ожидания нового REST endpoint.
Возможность улучшения без нарушения существующих клиентов
Добавление новых функций или изменение существующих в GraphQL не нарушает текущие интеграции благодаря его гибкой структуре запросов. Эта возможность гарантирует, что улучшения могут быть сделаны без нарушения совместимости с существующими клиентами.
Актуальная документация
Благодаря функции интроспекции GraphQL документация автоматически генерируется и обновляется с каждым изменением. Это гарантирует, что вся информация, предоставленная разработчикам, актуальна, уменьшая проблемы интеграции и запросы в поддержку, связанные с устаревшей документацией — проблема, которую часто испытывают с документацией REST API.
Ознакомьтесь с нашей документацией GraphQL и нашей документацией REST чтобы увидеть разницу.
Аналогия
Представьте, что вы в ресторане с меню, которое позволяет вам заказывать блюда ровно так, как вы их хотите, по сравнению с другим рестораном, где вы можете выбрать только из установленных комплексов. GraphQL похож на первый ресторан:
GraphQL предоставляет большую гибкость, эффективность и простоту для получения данных чем REST API, особенно при изменении или увеличении ваших потребностей.
Как Zonos использует GraphQL
При модернизации нашей платформы за последние пару лет Zonos решила разрабатывать новую функциональность на GraphQL для нашего API вместо REST. Мы решили сделать это потому, что наши данные сложны и взаимосвязаны, во многом как данные, которые привели Facebook к созданию GraphQL. Эта сложность усложняет создание масштабируемых REST API, потому что способы, которыми разработчикам нужно получать и использовать данные, варьируются кардинально между реализациями, а REST не гибкий.
GraphQL аккуратно решает эту проблему, позволяя разработчикам, реализующим наш API, выбирать ровно те данные, которые им нужны, и способ их получения. Это позволяет им вписаться в свои рабочие процессы без того, чтобы Zonos приходилось выполнять индивидуальную работу (пока они ждут) для каждой ситуации.
Комбинированный результат использования GraphQL и модернизаций в нашей платформе сделал наш API более производительным, сделал интеграцию Zonos в ваши системы быстрее и сделал возможным для Zonos быстрее доставлять новые функции.
Лучшие функции
Zonos постоянно разрабатывает новые функции, и GraphQL является первой (и обычно единственной) для получения этих обновлений. Напротив, наши REST API считаются устаревшими и не могут получить доступ ко многим нашим новым функциям.
Примеры функций, ограниченных GraphQL:
Была ли эта страница полезной?