Qu'est-ce que GraphQL ?
GraphQL est une alternative pour communiquer avec les APIs qui est particulièrement adaptée aux structures de données complexes et à la construction d'interfaces par-dessus celles-ci. Contrairement à la manière de traiter les données comme des morceaux séparés et autonomes, GraphQL montre comment les morceaux de données se connectent et se rapportent les uns aux autres, facilitant ainsi la demande et la réception d'informations.
Pensez à 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 le plus possible de la base de données, vous laissant choisir exactement quelles données vous souhaitez et comment vous les obtenez, offrant ainsi un énorme avantage en termes de performance.
GraphQL a été créé par Facebook pour résoudre le problème de l'évolutivité avec des structures de données complexes. En raison de leur adoption réussie, de plus en plus d'entreprises ont commencé à réaliser les avantages de l'utilisation de GraphQL pour leurs APIs.
Vous connaissez déjà REST ? GraphQL vous semblera familier.
Les APIs GraphQL sont plus faciles à utiliser que vous ne le pensez. Si vous êtes habitué à travailler avec des APIs REST, voici comment les concepts fondamentaux de REST se traduisent en GraphQL.
| Fonctionnalité | REST | GraphQL |
|---|---|---|
| Point de terminaison | Les requêtes sont effectuées vers plusieurs points de terminaison pour différentes actions | Toutes les requêtes sont effectuées vers un seul point de terminaison (par exemple, /graphql) |
| Récupération de données | Utilisez des 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 ainsi le sur-récupération ou la sous-récupération |
| Modification des données/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 exemple, créer des parties, calculer les coûts d'importation) |
| Format de réponse | Des formats de réponse fixes renvoient tous les champs prédéfinis, qu'ils soient nécessaires ou non | Des réponses flexibles permettent de spécifier exactement les champs à inclure, réduisant le transfert de données inutiles (Si cette flexibilité semble compliquée, utilisez simplement les exemples de requêtes pré-écrits dans notre documentation pour une expérience RESTful) |
| Connexion des données | Plusieurs requêtes sont souvent nécessaires pour récupérer des données liées | Des requêtes imbriquées permettent de récupérer des données liées en une seule requête (par exemple, les détails de la partie et les articles d'expédition ensemble). Les utilisateurs peuvent également créer 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 de données précise, à l'utilisation d'un seul point de terminaison et à des capacités améliorées de regroupement et de mise en cache.
Récupération de données précise
Un défi courant avec REST est le sur-récupération ou la sous-récupération des données : soit obtenir 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 la performance, mais simplifie également le processus pour ceux qui interagissent avec l'API, rendant le système plus efficace et convivial.
Exemples de la façon dont cela est utile :
- Cela permet aux développeurs frontend de récupérer exactement les données dont ils ont besoin pour leurs composants UI, réduisant le nombre de voyages aller-retour vers le serveur et améliorant la performance.
- Imaginez que vous souhaitiez obtenir une classification de code HS, cartonisation, évaluation d'expédition et un devis landed cost sur des articles dans un checkout. Si vous êtes intégré via l'API GraphQL, vous pouvez effectuer un seul appel avec les flux de travail nécessaires pour obtenir tout ce dont vous avez besoin (et rien de ce dont vous n'avez pas besoin) dans une seule réponse. En revanche, avec les APIs REST, vous devriez d'abord appeler le Classify REST API, puis appeler le Rating REST API séparément par la suite, et enfin brancher cette classification et cette évaluation d'expédition dans votre troisième appel à lLanded Cost REST API. Toutes ces APIs REST renverraient chaque morceau d'information qu'elles peuvent, vous obligeant à parcourir la réponse pour les données dont vous avez besoin. Cette économie de temps a un impact sur le retour rapide d'un landed cost, avant que l'acheteur ne parte.
Point de terminaison unique
Les APIs GraphQL ont généralement un point de terminaison unique, contrairement aux APIs REST qui ont souvent plusieurs points de terminaison pour différentes ressources et actions. Cela rend la gestion et la compréhension de l'API plus simples.
Regroupement et mise en cache
La capacité de GraphQL à regrouper les requêtes et son support pour les stratégies de mise en cache entraînent des améliorations significatives de performance. 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 APIs 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 fournit une 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 graphe pour obtenir exactement ce dont elles ont besoin au lieu d'attendre un nouveau point de terminaison REST.
Capacité à s'améliorer sans perturber les clients existants
Ajouter de nouvelles fonctionnalités ou modifier des fonctionnalités 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 rompre 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 changement. 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 APIs 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 aimez, par rapport à un autre restaurant où vous ne pouvez choisir que parmi des repas 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 ne voulez que 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 sur mesure : Nos API GraphQL peuvent être facilement combinées pour créer des solutions plus personnalisées, semblable à un restaurant de style buffet où vous pouvez créer un plat unique exactement comme vous en avez besoin, en utilisant des ingrédients qu'ils ont déjà. En revanche, une API REST est comme une boulangerie avec des produits préfabriqués emballés dans des paniers : vous ne pouvez commander que ce qui a déjà été créé et vous ne pouvez pas choisir de ramener uniquement la pièce que vous voulez.
- Moins d'attente : Puisque vous pouvez obtenir toutes les informations dont vous avez besoin en une seule demande, c'est comme demander à votre serveur d'apporter votre entrée, votre plat principal et votre dessert en même temps, plutôt que d'attendre entre les plats. La plupart des API REST nécessitent que vous envoyiez plusieurs demandes pour obtenir différentes informations.
- Facilité de modification des 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 (endpoint) 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 à mesure que vos besoins changent ou augmentent.
Comment Zonos utilise GraphQL
Tout en modernisant notre plateforme au cours des dernières années, Zonos a fait le choix de construire de nouvelles fonctionnalités en utilisant GraphQL pour notre API au lieu de REST. Nous avons décidé de le faire parce que nos données sont complexes et interconnectées, tout comme les données qui ont conduit Facebook à créer GraphQL. Cette complexité rend difficile la construction d'API REST évolutives car les manières 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 qui implémentent notre API de choisir exactement quelles données ils veulent et comment ils les obtiennent. Cela leur permet de les intégrer dans leurs flux de travail sans que Zonos ait besoin de faire un 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 à de nombreuses nouvelles fonctionnalités.
Exemples de fonctionnalités limitées à GraphQL :
- Inclusive pricing
- API des étiquettes
- Nouveau Checkout et Hello
- Tailles de boîte dans la réponse API
- Reporting du tableau de bord
- Capacité à demander un devis DDP si possible, mais toujours retourner un devis DDU si DDP n'est pas disponible pour ce pays avec ce niveau de service
- Détail des droits, taxes et frais (informations au niveau des articles, frais spécifiques) — Le tableau de bord est alimenté par GraphQL et montre ces données pour tous les magasins, mais la réponse de l'API REST n'inclut pas ce niveau de détail
- Mode test (à venir)
Pourquoi GraphQL
Découvrez pourquoi nous recommandons l'intégration via GraphQL plutôt que REST.
Chez Zonos, nous proposons deux principaux types d'APIs pour l'intégration : GraphQL et REST. Bien que les APIs REST existent depuis plus longtemps et soient peut-être plus familières pour beaucoup, nous avons opté pour GraphQL afin d'offrir plus de flexibilité et d'innovation rapide. Bien que les deux soient encore pris en charge, ce guide explique pourquoi GraphQL n'est pas 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.