Limites de débit API et utilisation de GraphQL

Cet article accompagne une vidéo de la chaîne YouTube ShopifyDevs. Il est le deuxième d’une série de trois articles rédigés par Zameer Masjedee, ingénieur solutions pour Shopify Plus. Zameer s’appuie ici sur les bases jetées dans son premier article, Introduction aux limites de débit, pour présenter les avantages de GraphQL et ses différences avec les API REST, et expliquer pourquoi, globalement, nous recommandons GraphQL.

Qu’est-ce que GraphQL ?

GraphQL a été conçu pour répondre à des insuffisances structurelles des API REST et pour simplifier certaines tâches. GraphQL, à la place des requêtes REST standards post, get, put et delete, classifie les requêtes en deux grandes catégories : query (requête) ou mutation.

Une query ne fait que lire des données, alors qu’une mutation fait tout le reste : création, mise à jour et suppression de données.

GraphQL vous permet d’interroger énormément d’informations. Comme nous l’avons expliqué dans la première partie de ce tutoriel, Introduction aux limites de débit, le coût en termes de limite de débit est en général assez faible. La réception d’un seul objet vaut un point et une mutation standard coûte environ 10 points.

L’un des avantages de GraphQL par rapport aux API REST est le nombre de requêtes HTTP que vous devez faire pour récupérer toutes les données dont vous avez besoin.

Prenons l’exemple d’un produit. Si nous avons l’identifiant d’un produit et que nous souhaitons récupérer toutes ses données, mais aussi ses images, variantes et champs méta, il faut effectuer quatre appels HTTP distincts, pour les quatre points de terminaison indépendants de notre implémentation REST.

Cela prendrait un dixième de notre seau de requêtes. Avec le taux de récupération de deux requêtes par seconde, il nous faudrait deux secondes pour retrouver notre capacité maximale.

Le fonctionnement de GraphQL est différent. Il permet de récupérer des données depuis plusieurs objets liés avec une seule requête GraphQL. Nous allons voir ensemble comment faire.

Utiliser l’application GraphQL Shopify

Passons sur notre boutique de démonstration, sur laquelle nous avons installé l’application GraphQL Shopify. Voici l’application :

Installez-la également sur votre boutique de développement. Elle est vraiment pratique pour tester GraphQL dans l’interface administrateur.

Vous voyez que c’est vraiment très rapide d’écrire une requête. Ici, pour le premier produit de la boutique, products(first: 1), nous voulons obtenir l’ID et la description. Nous voulons aussi examiner la première variante, variants(first: 1) sur la boutique et obtenir son code-barres barcode. Enfin, nous voulons récupérer certaines informations à propos des éléments images(first: 1) et metafields(first: 10).

Voyons ce qui se passe lorsque nous exécutons cette requête.

Nous récupérons uniquement les informations que nous avons demandées. La requête a renvoyé l’identifiant, la description et les informations sur les variantes demandées, mais aucune autre donnée, comme les identifiants des variantes. Seules les données demandées sont renvoyées.

Ce n’est malheureusement pas le cas avec les API REST. Lorsque nous demandons des informations pour un identifiant de commande, nous récupérons toutes les données associées à cette commande, c’est-à-dire environ 350 lignes de données JSON. Dans Insomnia, nous ne pouvons pas indiquer de paramètre de champ pour préciser le champ qui nous intéresse.

GraphQL au contraire nous permet de faire certaines adaptations. Créons par exemple une autre requête pour une commande spécifique.

Cette requête GraphQL doit récupérer exactement la même chose que l’exemple ci-dessus dans Insomnia, c’est-à-dire une commande spécifique, mais une seule propriété nous intéresse. Nous voulons savoir si la commande a été entièrement payée ou pas, afin de pouvoir la stocker dans notre base de données ou la traiter. Nous utilisons donc l’élément fullyPaid.

La requête renvoie la réponse true (vrai), ce qui signifie que la commande a été entièrement payée. Cette requête ne nous a coûté qu’un point sur les 1 000 points disponibles et le taux de récupération est de 50 points par seconde.

Nous avons ainsi une vision très précise de la limite de débit et du nombre de points restants.

Vous pouvez aussi obtenir ces informations sur la limite de débit avec les appels d’API REST. Nous utilisons Insomnia dans ce tutoriel, mais vous pouvez choisir le client HTTP que vous préférez, Postman par exemple. Revenons à la requête order que nous avons faite avec Insomnia.

Dans la réponse de l’en-tête, l’en-tête Shopify appelé x-Shop-api-call-limit nous indique l’utilisation de la limite de débit API.

Si nous exécutons cet appel plusieurs fois de suite rapidement, nous voyons que le chiffre est mis à jour. Cela prend un peu de temps, car deux appels sont restaurés chaque seconde pour le calcul de la limite restante, selon l’algorithme du seau qui fuit. Mais vous aurez toujours une vision exacte à un instant T de la limite de débit API encore disponible.

Avantages de GraphQL par rapport à REST

Un autre avantage majeur de GraphQL est qu’il nous permet chez Shopify de connaître plus précisément les données que vous interrogez.

Lorsque vous faites un appel à une API REST, nous ne savons pas quelles données vous utilisez ou non, et cela a un impact sur les services que nous pouvons vous proposer. Lorsque vous utilisez une mutation GraphQL, nous savons quels champs vous récupérez ou quels types de mutations vous exécutez. Ainsi, si des fonctionnalités doivent être abandonnées, nous pouvons vous prévenir directement, car nous savons que vous les utilisez. De même, si nous avons besoin de bêta-testeurs pour un nouveau produit, nous pouvons vous contacter si ces tests sont susceptibles de vous intéresser.

GraphQL présente plusieurs autres avantages, mais le dernier que nous allons étudier est lié au fait que GraphQL possède son propre schéma. Vous savez ainsi exactement ce à quoi vous avez accès lorsque vous préparez vos requêtes et vos mutations, et le risque d’erreur est bien moindre qu’avec les implémentations REST.

En termes de structure et d’architecture, le nombre de requêtes HTTP requises et le volume de données renvoyées sont des points fondamentaux. Mais la technologie GraphQL nous permet aussi de faire des choses qui sont tout simplement impossibles avec les API REST, et c’est là un avantage majeur. GraphQL permet par exemple d’effectuer des opérations en bloc dans Shopify. Voyons cela plus en détail.

API d’opérations en bloc : une fonctionnalité proposée uniquement par GraphQL

Shopify propose des fonctionnalités disponibles uniquement avec GraphQL. Il s’agit pour la plupart de fonctionnalités qui améliorent l’efficacité globale. Pensez-y lorsque vous devrez choisir entre REST et GraphQL, il peut être utile de rester ouvert à plus de possibilités.

Qu’est-ce qu’une mutation de requête en bloc ?

Une mutation de requête en bloc vous permet de demander à Shopify d’exécuter pour vous une tâche très longue et de vous informer lorsqu’elle est terminée.

Il vous suffit de deux étapes :

1. Transmettez la requête à Shopify, qui la traitera et vous informera dès qu’elle sera terminée.
2. Téléchargez les données.

Si vous n’utilisez pas de requêtes en bloc, vous devrez généralement paginer vos ensembles de données. Pour REST, par exemple, une réponse renvoie 250 éléments au maximum. Pour GraphQL, la limite dépend du coût, mais le nombre d’éléments sera toujours limité quoi qu’il en soit. Ce n’est pas le cas avec une API d’opérations en bloc.

Prenons l’exemple figurant dans le tutoriel sur l’exécution d’opérations en bloc avec l’API administrateur GraphQL, dans la documentation pour les développeurs.

Cette requête pourrait concerner 100 000 produits, ou même un million de produits. Évidemment, plus le chiffre est élevé et plus le temps de traitement est long, mais au final nous pouvons obtenir une réponse qui inclut toutes les données, en particulier l’identifiant et le titre, que nous pouvons sauvegarder dans nos propres serveurs.

Ainsi, vous entrez une requête, et elle est traitée. Vous pouvez également définir un autre point de terminaison pour suivre le statut de la requête et savoir quand elle est terminée, et enfin vous pouvez télécharger le fichier.

Quels sont les cas d’utilisation possibles pour ce type de requête ?

Si votre application traite des données, vous voudrez peut-être proposer aux marchands des tableaux de bord complets. Vous pouvez télécharger toutes leurs données en bloc la première fois qu’ils installent votre application et ainsi exécuter vos outils d’informatique décisionnelle pour leur donner les informations qu’ils attendent.

Ce type de requête est aussi très pratique si vous utilisez des webhooks. Ceux-ci sont très utiles, car leurs réponses sont toujours garanties. Avec une mutation en bloc, vous pouvez implémenter un rapprochement ou une tâche cron planifiée, qui récupèrera chaque jour toutes les commandes de la veille.

Dans l’exemple ci-dessus, nous récupérons tous les produits, mais vous pouvez très bien passer des paramètres supplémentaires, par exemple, si vous souhaitez récupérer uniquement les produits créés un jour donné. Nous savons que nous pouvons avoir une liste exhaustive de toutes les données pour lesquelles nous avons reçu ou non tous les webhooks.

Mettre à jour les articles en stock avec des opérations de requête en bloc

Dernier exemple de cas d’utilisation, la mutation inventoryBulkAdjustQuantityAtLocation. Elle est vraiment intéressante (même si son nom est un peu long !).

Elle permet de mettre à jour jusqu’à 100 quantités d’articles en stock en un seul lieu, avec une seule mutation. Dans REST, il faudrait un appel par niveau de stock, soit 100 appels pour mettre à jour ces 100 niveaux. Dans GraphQL, une mutation suffit, et cette mutation ne coûte que 10 points sur votre limite de 1 000 points ou sur votre taux de récupération de 50.

Créer avec GraphQL

Comme nous avons pu le voir, GraphQL offre de nombreux avantages. C’est particulièrement vrai si vous travaillez avec des marchands qui ont plusieurs points de vente ou si d’autres facteurs ont un impact sur la gestion du stock, et que vous souhaitez assurer la synchronisation de Shopify avec d’autres systèmes. Certaines de ces requêtes les plus efficaces et les plus évolutives sont spécifiques à GraphQL. Voilà pourquoi c’est une option qui mérite d’être étudiée.

---

Publié par Maud Leuenberger. Maud est la rédactrice en chef du blog français de Shopify.

Texte original par Zameer Masjedee. Traduction par Solenn Marchand.