Découvrez pourquoi nous recommandons l'intégration via GraphQL plutôt que REST.
Chez Zonos, nous proposons deux types principaux d'API pour l'intégration : GraphQL et REST. Bien que les API REST existent depuis plus longtemps et puissent être plus familières pour beaucoup, nous sommes passés à GraphQL pour permettre plus de flexibilité et une innovation plus rapide. Bien que les deux soient toujours prises en charge, ce guide explique pourquoi GraphQL est non seulement l'avenir de nos intégrations, mais aussi l'avenir des intégrations en général et un outil plus puissant pour répondre à vos besoins aujourd'hui.
GraphQL est une manière alternative de communiquer avec les API, particulièrement adaptée aux structures de données complexes et à la construction d'interfaces par-dessus. Contrairement au traitement des données comme des éléments séparés et autonomes, GraphQL montre comment les éléments de données se connectent et se rapportent les uns aux autres, facilitant la demande et la réception d'informations.
Considérez GraphQL comme un langage de requête qui vous permet de parler à l'API comme si vous parliez directement à la base de données. L'utilisation de GraphQL vous permet de vous rapprocher autant que possible de la base de données, vous laissant choisir les données que vous voulez et comment les obtenir, offrant un avantage de performance considérable.
GraphQL a été créé par Facebook pour résoudre le problème de la mise à l'échelle avec des structures de données complexes. En conséquence de leur adoption réussie, de plus en plus d'entreprises commencent à réaliser les avantages de l'utilisation de GraphQL pour leurs API.
Vous connaissez déjà REST ? GraphQL vous semblera familier.
Les API GraphQL sont plus faciles à utiliser que vous ne le pensez. Si vous êtes habitué aux API REST, voici comment les concepts fondamentaux de REST se traduisent en GraphQL.
Fonctionnalité↕
REST↕
GraphQL↕
Point de terminaison
Les requêtes sont adressées à plusieurs points de terminaison pour différentes actions
Toutes les requêtes sont adressées à un seul point de terminaison (par ex., /graphql)
Récupération de données
Utilisez les méthodes GET sur des points de terminaison spécifiques pour récupérer des données
Utilisez des requêtes pour demander exactement les données nécessaires, réduisant l'over-fetching ou l'under-fetching
Modification/actions
Utilisez des méthodes HTTP comme POST, PUT, PATCH ou DELETE pour modifier ou traiter des données
Utilisez des mutations pour effectuer des opérations (par ex., créer des parties, calculer des landed costs)
Format de réponse
Formats de réponse fixes renvoyant tous les champs prédéfinis, qu'ils soient nécessaires ou non
Réponses flexibles permettant de spécifier exactement les champs à inclure, réduisant le transfert de données inutile (Si cette flexibilité semble compliquée, utilisez simplement les exemples de requêtes pré-écrits dans notre documentation pour une expérience proche de REST)
Connexion de données
Plusieurs requêtes sont souvent nécessaires pour récupérer des données liées
Les requêtes imbriquées permettent de récupérer des données liées en une seule requête (par ex., détails de partie et articles d'envoi ensemble). Les utilisateurs peuvent également construire des flux de travail pour gérer plusieurs mutations dans une seule requête GraphQL, réduisant la complexité et améliorant l'efficacité
Avantages de GraphQL
Réponses plus rapides
GraphQL fournit des réponses plus rapides grâce à une récupération précise des données, l'utilisation d'un seul point de terminaison et des capacités améliorées de batching et de mise en cache.
Un défi courant avec REST est l'over-fetching ou l'under-fetching de données — obtenir soit trop d'informations inutiles, soit pas assez de ce qui est nécessaire en une seule fois. GraphQL élimine cela en permettant de demander exactement ce qui est nécessaire — ni plus, ni moins. Cette spécificité améliore non seulement les performances, mais simplifie également le processus pour ceux qui interagissent avec l'API, rendant le système plus efficace et convivial.
Exemples d'utilité :
Cela permet aux développeurs frontend de récupérer exactement les données nécessaires pour leurs composants UI, réduisant le nombre d'allers-retours au serveur et améliorant les performances.
Imaginez que vous souhaitez obtenir une classification de code SH, une cartonization, une tarification d'envoi et un devis Landed Cost sur les articles d'un checkout. Si vous êtes intégré via l'API GraphQL, vous pouvez effectuer un seul appel avec les workflows nécessaires pour obtenir tout ce dont vous avez besoin (et rien de superflu) en une seule réponse. En revanche, avec les API REST, vous devriez d'abord appeler l'API REST Classify, puis appeler séparément l'API REST Rating, et enfin intégrer cette classification et tarification d'envoi dans votre troisième appel à l'API REST Landed Cost. Toutes ces API REST renverraient chaque information disponible, vous obligeant à analyser la réponse pour les données dont vous avez besoin. Cette économie de vitesse a un impact sur le retour rapide d'un landed cost complet, avant que l'acheteur ne parte.
Les API GraphQL ont généralement un seul point de terminaison, contrairement aux API REST qui ont souvent plusieurs points de terminaison pour différentes ressources et actions. Cela simplifie la gestion et la compréhension de l'API.
La capacité de GraphQL à regrouper les requêtes et son support des stratégies de mise en cache conduisent à des améliorations significatives des performances. Ces fonctionnalités réduisent la charge sur les réseaux et les serveurs, se traduisant par des interactions plus rapides et plus fiables pour les utilisateurs.
Schémas bien définis
Les API GraphQL sont basées sur un schéma fortement typé. Ce schéma définit la structure des données disponibles et les opérations qui peuvent être effectuées. Cela apporte de la clarté sur les données disponibles et comment y accéder, ce qui peut améliorer la productivité des développeurs et réduire les erreurs. Par exemple, les équipes frontend peuvent explorer le graph pour obtenir exactement ce dont elles ont besoin au lieu d'attendre un nouveau point de terminaison REST.
Capacité d'améliorer sans casser les clients existants
L'ajout de nouvelles fonctionnalités ou la modification de celles existantes dans GraphQL ne perturbe pas les intégrations actuelles, grâce à sa structure de requête flexible. Cette capacité garantit que des améliorations peuvent être apportées sans compromettre la compatibilité avec les clients existants.
Documentation à jour
Grâce à la fonctionnalité d'introspection de GraphQL, la documentation est automatiquement générée et mise à jour à chaque modification. Cela garantit que toutes les informations fournies aux développeurs sont actuelles, réduisant les problèmes d'intégration et les tickets de support liés à une documentation obsolète — un défi couramment rencontré avec la documentation des API REST.
Imaginez que vous êtes dans un restaurant avec un menu qui vous permet de commander des plats exactement comme vous les souhaitez, comparé à un autre restaurant où vous ne pouvez choisir qu'entre des menus fixes. GraphQL est comme le premier restaurant :
Obtenez exactement ce que vous voulez : Avec GraphQL, vous pouvez demander exactement les données dont vous avez besoin, ni plus, ni moins. Imaginez que vous voulez seulement le nom et le prix d'un plat, pas toute la liste des ingrédients. Avec les API REST, vous devez obtenir tous les détails du plat et ignorer les parties dont vous n'avez pas besoin.
Composez un plat personnalisé : Notre API GraphQL peut être facilement combinée pour créer des solutions plus personnalisées, similaire à un restaurant buffet où vous pouvez créer un plat unique exactement comme vous en avez besoin, en utilisant les ingrédients qu'ils ont déjà. En revanche, une API REST est comme une boulangerie avec des produits préfabriqués emballés en paniers — vous ne pouvez commander que ce qui a déjà été créé et vous ne pouvez pas choisir de repartir seulement avec la pièce que vous voulez.
Moins d'attente : Puisque vous pouvez obtenir toutes les informations dont vous avez besoin en une seule requête, c'est comme demander à votre serveur d'apporter votre entrée, plat principal et dessert en même temps, plutôt que d'attendre entre les services. La plupart des API REST nécessitent d'envoyer plusieurs requêtes pour obtenir différentes informations.
Facile de modifier les commandes : Si les besoins en données de votre application changent, GraphQL facilite l'ajustement. Vous changez simplement la requête pour ce dont vous avez besoin. Avec REST, vous pourriez devoir attendre que la cuisine (backend) crée un nouveau plat (point de terminaison) pour le menu, ce qui prend plus de temps.
GraphQL offre plus de flexibilité, d'efficacité et de simplicité pour récupérer des données que les API REST, surtout lorsque vos besoins changent ou grandissent.
Lors de la modernisation de notre plateforme au cours des dernières années, Zonos a choisi de construire de nouvelles fonctionnalités en utilisant GraphQL pour notre API au lieu de REST. Nous avons pris cette décision parce que nos données sont complexes et interconnectées, un peu comme les données qui ont conduit Facebook à créer GraphQL. Cette complexité rend difficile la construction d'API REST évolutives, car les façons dont les développeurs doivent récupérer et utiliser les données varient considérablement entre les implémentations, et REST n'est pas flexible.
GraphQL résout élégamment ce problème en permettant aux développeurs implémentant notre API de choisir exactement les données qu'ils veulent et comment les obtenir. Cela leur permet de l'intégrer dans leurs flux de travail sans que Zonos ait besoin de faire du travail personnalisé (pendant qu'ils attendent) pour chaque situation.
Le résultat combiné de l'utilisation de GraphQL et des modernisations de notre plateforme a rendu notre API plus performante, a accéléré l'intégration de Zonos dans vos systèmes et a permis à Zonos de livrer de nouvelles fonctionnalités plus rapidement.
Meilleures fonctionnalités
Zonos développe continuellement de nouvelles fonctionnalités, et GraphQL est le premier (et généralement le seul) à recevoir ces mises à jour. En revanche, nos API REST sont considérées comme en fin de vie et ne peuvent pas accéder à nombre de nos nouvelles fonctionnalités.
Exemples de fonctionnalités limitées à GraphQL :
Inclusive pricing
Labels API
Nouveau Checkout et Hello
Tailles de colis dans la réponse API
Rapports Dashboard
Capacité de demander un devis DDP si possible, mais de renvoyer quand même un devis DDU si le DDP n'est pas disponible pour ce pays avec ce niveau de service
Ventilation détaillée des droits, taxes et frais (informations au niveau article, frais spécifiques) — Dashboard est alimenté par GraphQL et affiche ces données pour toutes les boutiques, mais la réponse de l'API REST n'inclut pas ce niveau de détail
Pourquoi GraphQL
Pourquoi GraphQL
Découvrez pourquoi nous recommandons l'intégration via GraphQL plutôt que REST.
Chez Zonos, nous proposons deux types principaux d'API pour l'intégration : GraphQL et REST. Bien que les API REST existent depuis plus longtemps et puissent être plus familières pour beaucoup, nous sommes passés à GraphQL pour permettre plus de flexibilité et une innovation plus rapide. Bien que les deux soient toujours prises en charge, ce guide explique pourquoi GraphQL est non seulement l'avenir de nos intégrations, mais aussi l'avenir des intégrations en général et un outil plus puissant pour répondre à vos besoins aujourd'hui.
Qu'est-ce que GraphQL ?
GraphQL est une manière alternative de communiquer avec les API, particulièrement adaptée aux structures de données complexes et à la construction d'interfaces par-dessus. Contrairement au traitement des données comme des éléments séparés et autonomes, GraphQL montre comment les éléments de données se connectent et se rapportent les uns aux autres, facilitant la demande et la réception d'informations.
Considérez GraphQL comme un langage de requête qui vous permet de parler à l'API comme si vous parliez directement à la base de données. L'utilisation de GraphQL vous permet de vous rapprocher autant que possible de la base de données, vous laissant choisir les données que vous voulez et comment les obtenir, offrant un avantage de performance considérable.
GraphQL a été créé par Facebook pour résoudre le problème de la mise à l'échelle avec des structures de données complexes. En conséquence de leur adoption réussie, de plus en plus d'entreprises commencent à réaliser les avantages de l'utilisation de GraphQL pour leurs API.
Vous connaissez déjà REST ? GraphQL vous semblera familier.
Les API GraphQL sont plus faciles à utiliser que vous ne le pensez. Si vous êtes habitué aux API REST, voici comment les concepts fondamentaux de REST se traduisent en GraphQL.
Avantages de GraphQL
Réponses plus rapides
GraphQL fournit des réponses plus rapides grâce à une récupération précise des données, l'utilisation d'un seul point de terminaison et des capacités améliorées de batching et de mise en cache.
Récupération précise des données
Un défi courant avec REST est l'over-fetching ou l'under-fetching de données — obtenir soit trop d'informations inutiles, soit pas assez de ce qui est nécessaire en une seule fois. GraphQL élimine cela en permettant de demander exactement ce qui est nécessaire — ni plus, ni moins. Cette spécificité améliore non seulement les performances, mais simplifie également le processus pour ceux qui interagissent avec l'API, rendant le système plus efficace et convivial.
Exemples d'utilité :
Point de terminaison unique
Les API GraphQL ont généralement un seul point de terminaison, contrairement aux API REST qui ont souvent plusieurs points de terminaison pour différentes ressources et actions. Cela simplifie la gestion et la compréhension de l'API.
Batching et mise en cache
La capacité de GraphQL à regrouper les requêtes et son support des stratégies de mise en cache conduisent à des améliorations significatives des performances. Ces fonctionnalités réduisent la charge sur les réseaux et les serveurs, se traduisant par des interactions plus rapides et plus fiables pour les utilisateurs.
Schémas bien définis
Les API GraphQL sont basées sur un schéma fortement typé. Ce schéma définit la structure des données disponibles et les opérations qui peuvent être effectuées. Cela apporte de la clarté sur les données disponibles et comment y accéder, ce qui peut améliorer la productivité des développeurs et réduire les erreurs. Par exemple, les équipes frontend peuvent explorer le graph pour obtenir exactement ce dont elles ont besoin au lieu d'attendre un nouveau point de terminaison REST.
Capacité d'améliorer sans casser les clients existants
L'ajout de nouvelles fonctionnalités ou la modification de celles existantes dans GraphQL ne perturbe pas les intégrations actuelles, grâce à sa structure de requête flexible. Cette capacité garantit que des améliorations peuvent être apportées sans compromettre la compatibilité avec les clients existants.
Documentation à jour
Grâce à la fonctionnalité d'introspection de GraphQL, la documentation est automatiquement générée et mise à jour à chaque modification. Cela garantit que toutes les informations fournies aux développeurs sont actuelles, réduisant les problèmes d'intégration et les tickets de support liés à une documentation obsolète — un défi couramment rencontré avec la documentation des API REST.
Consultez notre documentation GraphQL et notre documentation REST pour voir la différence.
Une analogie
Imaginez que vous êtes dans un restaurant avec un menu qui vous permet de commander des plats exactement comme vous les souhaitez, comparé à un autre restaurant où vous ne pouvez choisir qu'entre des menus fixes. GraphQL est comme le premier restaurant :
GraphQL offre plus de flexibilité, d'efficacité et de simplicité pour récupérer des données que les API REST, surtout lorsque vos besoins changent ou grandissent.
Comment Zonos utilise GraphQL
Lors de la modernisation de notre plateforme au cours des dernières années, Zonos a choisi de construire de nouvelles fonctionnalités en utilisant GraphQL pour notre API au lieu de REST. Nous avons pris cette décision parce que nos données sont complexes et interconnectées, un peu comme les données qui ont conduit Facebook à créer GraphQL. Cette complexité rend difficile la construction d'API REST évolutives, car les façons dont les développeurs doivent récupérer et utiliser les données varient considérablement entre les implémentations, et REST n'est pas flexible.
GraphQL résout élégamment ce problème en permettant aux développeurs implémentant notre API de choisir exactement les données qu'ils veulent et comment les obtenir. Cela leur permet de l'intégrer dans leurs flux de travail sans que Zonos ait besoin de faire du travail personnalisé (pendant qu'ils attendent) pour chaque situation.
Le résultat combiné de l'utilisation de GraphQL et des modernisations de notre plateforme a rendu notre API plus performante, a accéléré l'intégration de Zonos dans vos systèmes et a permis à Zonos de livrer de nouvelles fonctionnalités plus rapidement.
Meilleures fonctionnalités
Zonos développe continuellement de nouvelles fonctionnalités, et GraphQL est le premier (et généralement le seul) à recevoir ces mises à jour. En revanche, nos API REST sont considérées comme en fin de vie et ne peuvent pas accéder à nombre de nos nouvelles fonctionnalités.
Exemples de fonctionnalités limitées à GraphQL :
Cette page a-t-elle été utile?