Débuter avec GraphQL

Cet article accompagne une vidéo de la chaine YouTube ShopifyDevs. Dans cet article, Chuck Kosman, ingénieur de lancement chez Shopify Plus, vous montrera les fonctionnalités de base de GraphQL avec Shopify. Nous verrons donc :

1. Ce qu’est GraphQL
2. Les outils que vous pouvez utiliser pour exploiter GraphQL
3. Un tutoriel pour apprendre à envoyer des requêtes GraphQL à la boutique d’un client

Qu’est-ce que GraphQL ?

Commençons par la question à un million, qu’est-ce que GraphQL ? Si vous allez sur le site officiel GraphQL.org, en haut de la page, vous verrez que GraphQL est présenté comme un langage de requêtes pour des API et un environnement d’exécution de ces requêtes avec vos données.

Les langages de requêtes sont des moyens expressifs et extrêmement structurés servant à appeler des données. Vous les connaissez probablement déjà dans le contexte des bases de données.

Nous parlons ici de l’utilisation de langages de requêtes pour une API. Si nous devions définir GraphQL de façon plus fonctionnelle, nous pourrions dire que « GraphQL est un moyen expressif et structuré d’obtenir des données provenant d’une autre application en demandant au système sous-jacent d’aller les chercher. »

Pour demander des données d’une autre application, vous connaissez certainement les API REST. On considère GraphQL comme une version améliorée de REST. REST a résolu de nombreux problèmes de ses prédécesseurs, mais GraphQL a été conçu précisément pour combler certaines lacunes de REST en lien avec des applications modernes. L’un des principaux problèmes que rencontre REST avec des applications modernes concerne le volume de données retournées. En effet, avec REST, ces applications vont soit chercher trop de données (overfetching), soit pas assez (underfetching).

Prenons l’exemple d’un restaurant pour mieux comprendre ces concepts, une analogie que l’on utilise depuis longtemps pour expliquer le fonctionnement des API.

L’analogie du marchand de glaces : explorer les concepts liés aux API

Pour cet exemple, notre restaurant sera un marchand de glaces. Parlons d’abord du problème de l’excès de données retournées, ou « overfetching ».

Dans Shopify, pour obtenir une information concernant une commande, nous devons utiliser ce point de terminaison (voir l’image ci-dessous) sur l’API REST de l’interface administrateur. Ensuite, en ajoutant la référence d’une commande, nous obtenons toutes les informations disponibles qui la concernent.

Prenons maintenant cette idée avec l’exemple d’un marchand de glaces ambulant. Imaginons que dans son menu, il ne propose que des glaces prédéfinies qui contiennent des garnitures qui ne vous intéressent pas toutes, et qu’aucune des combinaisons de garnitures qu’il propose ne vous convienne. Le marchand de glaces va passer beaucoup de temps pour préparer la glace avec toutes les garnitures qui sont indiquées dans son menu. Mais si en tant que client, vous n’aimez pas ou n’avez pas besoin de certaines de ces garnitures, c’est à vous de les enlever. Il y a un vrai déficit d’efficacité pour les deux parties.

À l’inverse, le problème du manque de données, ou « underfetching », implique que vous n’avez pas reçu suffisamment de données pour votre requête. Cela se produit souvent lorsque l’on recherche des données profondément imbriquées.

Voici un exemple dans Shopify, où nous tentons d’extraire les champs méta d’un ensemble de produits. Nous commençons par formuler une requête GET pour tous les produits, mais cette requête ne nous donne pas toutes les données qui nous intéressent.

Dans ce cas, nous avons donc dû utiliser un autre point de terminaison et ajouter les identifiants pour pouvoir accéder aux champs méta que nous voulons. Vous avez peut-être entendu parler de ce problème comme le problème n+1. Nous avons formulé une requête pour obtenir la liste entière des produits et avons ensuite dû formuler n requêtes supplémentaires pour accéder à toutes les ressources qui nous intéressaient. Pour reprendre notre analogie, c’est comme si nous demandions une glace et que pour chaque garniture que nous voulons, nous devions revenir au camion du marchand pour ajouter une garniture à la fois.

Cela manque cruellement d’efficacité et de flexibilité.

Avec GraphQL, vous indiquez précisément les données que vous voulez extraire avec votre requête, et vous obtenez seulement les données que vous avez demandées. De manière intéressante, dans l’image qui suit, vous remarquerez que nous utilisons une requête POST pour ce point de terminaison de l’API admin/API/GraphQL.json, et qu’avec cette requête, nous fournissons une structure de données imbriquées. Cette structure de données imbriquées est un exemple de pseudocode qui permet de demander certains champs de produits avec un identifiant spécifique pour chaque produit.

Donc dans ce cas, supposons que nous soyons intéressés par les titre (admin/API/GraphQL.json) et ancre d’URL (handle), puis par des champs dans les variantes (variants) des produits. Nous pourrions l’indiquer au niveau des ..., sous variants dans l’image ci-dessous. Avec ce type de requêtes, nous obtenons seulement les données que nous avons explicitement demandées.

Avec notre marchand de glaces, cela revient à se rendre au comptoir, demander les goûts et les garnitures que nous voulons, et obtenir exactement cela en une seule demande efficace et flexible.

Comme nous précisons les données exactes qui nous intéressent pour chaque requête, les données dont il est question sont facilement identifiées par le serveur qui exécute la requête, le client, c’est-à-dire nous, nos collègues et le reste de l’application. C’est un avantage considérable pour la clarté et la rapidité d’exécution. Cela permet aussi une itération front-end rapide car nous n’utilisons plus qu’un seul point de terminaison. Le développeur front-end n’a ainsi plus besoin de jongler avec plusieurs points de terminaison. En d’autres mots, c’est la structure de notre requête qui détermine les données retournées, et non les points de terminaison que nous devons appeler successivement.

Vous vous demandez peut-être, mais s’il n’y a qu’un seul point de terminaison, comment savoir ce que l’on peut demander ?

Le grand intérêt de GraphQL se trouve dans une documentation transparente sur ses capacités que l’on appelle « schéma ». Nous parlons de schéma fortement typé, car les modèles de données que vous obtenez sont définis par des types sous-jacents. C’est ce qui rend GraphQL si intuitif, car au moment où vous écrivez ou formatez votre requête, vous savez si vous faites une erreur ou non.

Ce sont tous ces éléments qui font de GraphQL le successeur plus efficace, plus puissant et plus flexible de REST.

Quels outils pour formuler des requêtes GraphQL dans Shopify ?

Maintenant que vous en savez plus sur GraphQL et ses avantages par rapport à REST, nous allons parler des outils que vous pouvez utiliser pour formuler des requêtes GraphQL dans Shopify.

Nous pourrions utiliser de simples requêtes cURL, mais ce serait passer à côté du schéma fortement typé que nous venons d’évoquer, qui est l’une des fonctionnalités les plus puissantes de GraphQL. Par contre, nous pouvons utiliser l’IDE (pour environnement de développement intégré) GraphiQL. Pour cela, il existe une implémentation pour l’API administrateur GraphQL et l’API Storefront. Nous parlerons de la différence entre ces deux API un peu plus loin, mais nous allons d’abord parler de l’implémentation dans l’API administrateur.

Ce dont vous avez besoin pour démarrer

Il existe une page très complète qui s’appelle « Shopify Admin API GraphiQL Explorer ». Vous pouvez commencer à la parcourir en mode lecture, mais si vous voulez suivre ce tutoriel, nous vous recommandons d’installer l’application Shopify GraphiQL.

Pour cela, vous devez avoir une boutique. Donc si vous n’avez pas encore de boutique de développement partenaire ou de boutique de test, ne vous inquiétez pas. La documentation vous explique comment procéder. Si vous devez configurer une boutique pour installer l’application, il existe un autre tutoriel appelé « Make Your First GraphQL Request » dans notre page de tutoriels de développement de Shopify.

Vous n’aurez que deux choses à faire parmi les trois suggérées en début de page. La première consiste à créer un compte partenaire. C’est ce que nous utilisons dans l’écosystème pour créer des solutions pour les marchands. C’est totalement gratuit.

Avec ce compte partenaire, vous allez créer une boutique de développement. Si vous en avez déjà une, il vous suffit de vous connecter. Nous allons laisser de côté la troisième proposition pour nos tutoriels GraphiQL. Toutefois, vous pouvez suivre cette troisième étape si vous préférez travailler avec un client HTTP indépendant. Mais nous verrons aussi à quoi cela ressemble.

Créez votre boutique si vous n’en avez pas. De plus, nous vous recommandons vivement d’ajouter des données de test pour qu’au moment de faire des requêtes, vous obteniez de vraies données qui ont du sens. Vous pouvez vous en tenir à des produits et des variantes, ou aller un peu plus loin et inclure des produits, des clients et des commandes si vous le souhaitez. Ce sont les trois éléments principaux.

L’environnement de développement intégré (IDE) de GraphQL pour Shopify

Nous allons maintenant revenir sur la page « Shopify Admin API GraphiQL Explorer » afin d’installer GraphiQL sur une boutique que nous avons déjà configurée. Nous vous conseillons d’installer l’application GraphiQL via le lien fourni sur la page. De notre côté, nous avons déjà configuré une boutique, getting-started-with-graphql.myshopify.com, que nous allons sélectionner dans les résultats de saisie semi-automatique.

À ce stade, vous devez définir les portées de l’application. Si la boutique n’est pas active, vous pouvez tout sélectionner sereinement. Si elle est active, nous vous conseillons plutôt de créer une boutique de développement ou une boutique de test, et de prendre vos précautions, car cette application peut lire et modifier du contenu. Faites donc très attention en sélectionnant les portées.

Pour ce tutoriel, vous aurez surtout besoin de produits qui pourront être affichés. Nous allons donc sélectionner toutes les portées, et lancer l’installation en cliquant sur « Install ». On nous demande alors de confirmer que nous voulons autoriser cette application pour toutes ces portées, et nous allons confirmer ce choix.

Une fois l’installation terminée, vous arrivez dans cette interface. Normalement, vous avez une ligne au format JSON contenant « shop » et « name » dans la colonne de gauche, et une colonne à droite, vide pour le moment. C’est ce que nous allons utiliser dans ce tutoriel, mais revenons d’abord sur les autres façons de travailler avec GraphQL.

Le client HTTP indépendant

Comme dit précédemment, vous pouvez aussi utiliser un client HTTP indépendant. Nous allons utiliser l’IDE GraphiQL pour ce tutoriel pour ne pas avoir à préciser le point de terminaison. Par chance, il n’y a qu’un seul point de terminaison dans GraphQL, c’est l’un des principaux avantages.

Nous n’avons pas non plus besoin de configurer les en-têtes. La vidéo vous montre à quoi elles ressemblent si vous préférez utiliser des en-têtes. Pour cela, vous aurez besoin de deux en-têtes. Vous devrez créer une application privée, et son mot de passe servira de jeton d’authentification sous le premier nom d’en-tête. Il faudra aussi définir le type de contenu en tant que application/json.

Attention à ne pas le confondre avec application/graphql, car il existe quelques différences. Vous avez généralement intérêt à utiliser application/json pour travailler avec un client HTTP indépendant. Si cela ne fonctionne pas, passez à application/graphql. Si vous voulez en savoir plus sur ce sujet, que vous ne savez plus où chercher dans la vidéo, ou que vous voulez tout reprendre depuis le début, vous pouvez consulter la page « Make Your FirstGraphQL Request ». Cette page parle de l’utilisation de GraphiQL avec un client HTTP indépendant.

Il y a aussi un excellent article, même un tutoriel complet, sur la configuration d’un client appelé « Insomnia ». Vous y trouverez un kit de requêtes préenregistrées que vous pouvez utiliser pour vous lancer directement. Cette ressource contient les en-têtes dont vous aurez besoin et quelques exemples de requêtes. C’est une excellente ressource à consulter après ce tutoriel.

Nous verrons quelques éléments sur le sujet. Enfin, sachez que l’IDE de GraphQL n’est pas adapté pour travailler sur de gros projets. C’est plutôt un outil qui sert à faire des tests. En production, vous ne pourrez pas non plus utiliser de client HTTP indépendant, vous devrez créer une application complète.

Pour les gros projets : les bibliothèques client de GraphQL

Pour créer une application de A à Z, nous recommandons vivement d’explorer les bibliothèques client de GraphQL. Du fait de la prévisibilité que confère le schéma fortement typé de GraphQL, vous pouvez associer plusieurs outils pour améliorer la rapidité et l’efficacité de vos travaux de développement. Vous avez peut-être entendu parler d’Apollo ou Relay, des bibliothèques client très utilisées, mais il en existe d’autres. Cela dépend des langages, des infrastructures logicielles, et des plateformes que vous visez.

Nous avons brièvement abordé ce sujet, mais notez qu’il existe deux types d’API permettant d’utiliser GraphQL. D’une part, il y a les API administrateur : REST et GraphQL. Les deux servent à développer des applications et des intégrations pour l’interface administrateur de Shopify. Elles sont en quelque sorte des extensions du back-office de Shopify. De l’autre côté, l’API Storefront a un usage bien différent et concerne tout ce qui touche aux expériences d’achat.

Nous avons aussi mis au point des kits de développement logiciel (ou SDK) pour le Web, Android, iOS et même des expériences de jeux via Unity. En plus du fait que GraphQL est le seul langage pour les API permettant de faire communiquer plusieurs boutiques en ligne, il possède bien d’autres avantages par rapport à REST. De fait, il y a certaines choses que vous pouvez faire en utilisant le flavor GraphQL de l’API administrateur qui ne sont pas faisables avec l’API REST.

En d’autres mots, Shopify mise vraiment sur GraphQL, et nous voyons bien les avantages de GraphQL par rapport aux API REST.

Que pouvez-vous faire avec des API administrateur GraphQL ?

Comme c’est déjà le cas depuis quelque temps, il y a certaines choses que vous ne pouvez faire que par l’intermédiaire de l’API administrateur GraphQL. Certaines sont énumérées ci-dessous en suivant la chronologie de leur sortie :

• Vous pouvez ajuster des stocks de produits de façon globale sur l’API administrateur GraphQL, ce qui est beaucoup plus efficace que de passer par l’API REST pour la même opération. C’est un vrai avantage pour la gestion des stocks à grande l’échelle.
• L’API de traductions ne fonctionne qu’avec GraphQL.
• La prise en charge de supports multimédia, pas seulement des images, mais aussi des vidéos et des modèles 3D, se fait via GraphQL.
• La modification des commandes, longtemps réclamée, se fait exclusivement depuis l’API administrateur GraphQL.
• Et à partir de maintenant, les API qui traitent les droits de douane et les taxes, ainsi que l’aperçu pour développeurs fonctionneront avec GraphQL seulement.

Attendez-vous à voir d’autres fonctionnalités passer entièrement sur GraphQL. Vous pouvez vous tenir informé de ces sorties en vous abonnant au journal des changements pour les développeurs pour connaitre toutes les nouveautés de l’API Shopify.

Mise en pratique : utiliser GraphQL dans Shopify

Maintenant que nos outils sont en place, nous allons formuler des requêtes dans la boutique Shopify de notre client à l’aide de l’IDE GraphiQL. Revenons à notre boutique, que nous avons laissée dans l’écran que nous avons entrevu quand nous avons installé l’IDE GraphiQL. Vous devriez voir une interface qui ressemble à ceci :

Pour commencer, nous allons faire un léger formatage pour avoir une présentation qui ressemble à ce que nous avons l’habitude de voir :

{
 shop {
 name
 }
}

Vous pouvez voir que la syntaxe utilisée par GraphQL, même dans cet exemple basique, ressemble un peu à la structure imbriquée de JSON. Nous allons cliquer sur le bouton « Play », représenté par une flèche. Ce bouton permet d’envoyer une requête, généralement pour obtenir des données qui nous intéressent. Nous allons donc cliquer sur cette flèche, où le message « Execute request » s’affiche, et nous obtenons un code JSON qui comporte deux propriétés.

La première s’appelle data. Nous remarquons déjà que la structure de cette propriété reprend exactement celle de la requête que nous avons formulée. Nous avons aussi la propriété shop, et la valeur de cette propriété est un objet. Cet objet a une clé nommée "name", que nous avons demandée. Le nom de notre boutique qui s’affiche est "Getting Started with GraphQL".

Ensuite, ce qui suit nous indique le coût de la requête. Si vous avez déjà travaillé avec une API Shopify, notamment l’API REST, vous savez que le nombre de requêtes que vous pouvez formuler est toujours limité, tout comme la vitesse à laquelle ces requêtes sortent de votre « seau » de requêtes. On parle du modèle du « seau percé ».

GraphQL a les mêmes limites, mais elles concernent le coût de la requête elle-même, et non le nombre d’appels. C’est pour cela que GraphQL est beaucoup plus efficace.

Rappelez-vous de l’exemple de l’overfetching ? C’est-à-dire beaucoup d’activité en arrière-plan pour des éléments dont vous n’avez pas forcément besoin. GraphQL détermine le coût de votre requête seulement en fonction de ce que vous avez demandé. C’est donc bien plus performant. Que pouvons-nous demander d’autre ici ?

Appuyons sur la touche « Entrée » et tapons la lettre C, disons pour currency code (la devise). Dès que nous écrivons la première lettre, la fonction de saisie semi-automatique nous propose tout ce que l’on peut demander dans notre shop. Pour être plus spécifique, toutes ces choses sont ce que l’on appelle des champs. Un champ est tout simplement une information qui vous intéresse.

C’est le schéma fortement typé de GraphiQL qui permet cela. GraphiQL sait tout ce que peut faire l’API, et sait exactement à quel nœud appartient chaque champ. Nous parlerons des nœuds un peu plus loin.

Pour connaitre la devise utilisée par notre boutique, il nous suffit donc de recliquer sur « Play », et nous obtenons la devise. La boutique utilise des dollars américains (USD).

Mais sans la saisie semi-automatique, comment savoir tout ce que peut faire cette API ? Où est ce schéma fortement typé dont nous avons déjà parlé ? Dans cet IDE GraphiQL, et avec un client HTTP indépendant qui dispose de bonnes capacités GraphQL, vous avez un onglet pour la documentation, dans notre cas, le schéma.

Cet onglet nous dit exactement ce que nous pouvons faire. C’est un peu mystérieux quand on découvre GraphQL.

Mais au début, vous pouvez faire deux choses. Vous pouvez :

1. Lire des données, c’est-à-dire faire une requête.
2. Faire une mutation. Les mutations permettent d’écrire des opérations.

Pour comparer avec des architectures CRUD dans REST, une requête permet de lire (read) des données. Les mutations s’occupent de tout le reste : c’est-à-dire créer (create), mettre à jour (update) et supprimer (delete).

Demander des données avec GraphQL

Sachez déjà que si on omet le terme query, l’action sera traitée par défaut comme une requête. Donc si nous écrivons query en début de colonne puis que nous appuyons sur « Play », nous obtiendrons exactement le même résultat que si nous ne l’écrivons pas. Commençons par les requêtes, et nous reviendrons ensuite sur les mutations.

La question que l’on se pose, c’est « Comment savoir si shop correspond à quelque chose que nous pouvons demander avec notre requête racine (QueryRoot) ? » La requête racine (QueryRoot), c’est tout simplement le point d’entrée pour demander des données.

Nous pouvons explorer le schéma pour avoir la réponse à cette question. Une requête retourne toujours un type de QueryRoot. En cliquant sur QueryRoot, vous accédez à tout un tas d’informations. Vous voyez toutes les requêtes que vous pouvez envoyer, et tout cela représente le schéma. C’est ce schéma qui définit les requêtes (query) que vous pouvez faire ou non. Elles sont classées par ordre alphabétique. Nous allons maintenant faire défiler la liste jusqu’à la lettre « s » pour query. Voici la définition du schéma de query. Nous pouvons lire que cela permet de retourner une ressource query correspondant au jeton d’accès de la requête. Nous n’avons même pas encore indiqué de jeton d’accès, encore une preuve de l’efficacité de GraphiQL.

Alors, que signifie cette définition du schéma en pratique ? Que signifie ce shop:shop! ?

Cela signifie que si nous formulons une requête pour obtenir un champ shop, nous obtiendrons un type, comme le démontre la présence de Shop. C’est comme cela que nous pouvons connaitre les champs qui peuvent faire l’objet d’une requête sous Shop. Le point d’exclamation signifie que le résultat ne peut pas être nul. Il faut que la requête renvoie un résultat.

Alors, comment savoir que le nom et la devise sont disponibles pour Shop ?

En cliquant sur le type Shop, vous verrez s’afficher toutes les requêtes que vous pouvez effectuer pour Shop. Vous pouvez faire défiler le schéma, et vous verrez qu’il y a beaucoup d’informations. C’est là que nous allons trouver notre currency code. Que renvoie cette requête ? Elle renvoie le code de la devise (CurrencyCode). Et que renvoie name ? Une chaine de caractères.

Voilà le cœur de l’efficacité du schéma fortement typé de GraphQL et des outils qui peuvent s’y greffer.

Nous pouvons ainsi voir toutes les requêtes possibles en temps réel et les informations que nous pouvons demander. En explorant le schéma, nous pouvons connaitre de façon précise et certaine les données nous pouvons obtenir ou non, et le format dans lequel elles apparaitront. Vous pouvez utiliser Shop pour de nombreuses opérations en production, mais vous voulez maintenant probablement approfondir sur certaines entités de données de votre boutique.

Prenons un exemple avec des produits.

Un exemple de requête sur des produits

Pour cet exemple, nous allons structurer notre requête au fur et à mesure, et la comparer au schéma afin que vous puissiez suivre. Nous verrons également une représentation visuelle de la façon dont ces types interagissent entre eux dans le schéma. 

Commençons par supprimer query, car comme nous l’avons vu, l’absence du terme query est exécutée comme une requête par défaut. Nous allons donc le supprimer pour ne garder que les accolades. Nous sommes bien dans QueryRoot, et nous allons nous intéresser à products.

La notion de products est un peu plus complexe.

Nous avons le champ products, puis une parenthèse qui indique first, after, last, before, sortKey. Enfin, on nous dit que nous obtenons le type ProductConnection. Ça fait beaucoup de termes d’un coup, alors commençons par le plus simple.

Utilisons products, sachant que la saisie semi-automatique sait déjà que products peut faire l’objet d’une requête dans notre QueryRoot. Nous allons rouvrir les accolades, et GraphQL va attendre une information ici. Que voulons-nous savoir concernant nos products ?

Admettons que nous voulons leur nom (title). Étrange, title n’apparait pas dans les suggestions. Mais pourquoi ?

En cliquant sur « Play », on nous dit que le champ title n’existe pas dans le type ProductConnection. Mais le schéma fortement typé de GraphQL nous aide vraiment beaucoup. Quelque chose dans ProductConnection! appelé edges apparait, et semble renvoyer [ProductEdge!]!!. Examinons d’abord ces edges. On comprend qu’ils contiennent des champs. Nous allons donc cliquer sur [ProductEdge!]!! pour savoir exactement à quoi ça sert.

On voit que cela peut renvoyer un cursor et un node, et il semblerait que ce node renvoie un type de product. C’est probablement ce que nous cherchons. Et ensuite, en cliquant sur node, vous verrez des choses plus classiques sur les types de product. Disons que nous n’avons besoin que de l’ID et du title.

Cliquons sur « Play » et nous obtenons un message d’erreur : you must provide one of first or last.

OK, qu’est-ce que ça veut dire ? Il manque un élément pour products, pour indiquer si l’on parle des premiers (first) ou des derniers (last) de la liste. Encore une fois, ce schéma fortement typé est vraiment utile.

Que veulent dire ces first et last ? Comme dans REST, vous ne pouvez pas obtenir tous les produits d’une liste simplement en demandant d’extraire son point de terminaison, car il y a une pagination. Nous utilisons une pagination basée sur un curseur conformément aux spécifications de GraphQL.

Voyons maintenant comment cela fonctionne. Pour ajouter ce que l’on appelle un argument, donc un qualificatif de requête, ouvrez d’abord les parenthèses. On nous propose déjà tous les arguments que nous pouvons utiliser. Nous allons commencer par le plus simple en choisissant first. Que renvoie ce first ? Nous devons fournir un nombre entier. Nous allons dire que nous voulons les 10 premiers produits de la liste. Nous allons laisser de côté edges et node pour le moment, mais nous y reviendrons très vite.

Nous pouvons cliquer sur « Play », et nous obtenons un résultat intéressant. Nous avons des data, qui retourne un objet qui contient la propriété products, qui contient elle-même l’objet edges, qui est un ensemble d’objets, chacun contenant un objet node, et enfin, les données que nous avons demandées. Dans ce cas, l’ID et le title de chaque produit.

Combien cela a-t-il coûté ? Ça fait 12 points.

Qu’est-ce que ça veut dire ? Et bien, dans GraphQL, votre seau (pour reprendre le modèle évoqué plus haut) peut contenir au maximum 1000 points, et se remplit de 50 points par seconde.

Comparez cela avec les 40 appels d’API REST que contient le seau d’une API REST, qui se remplit de seulement deux appels par seconde. C’est clair : GraphQL est bien plus efficace que REST, même sans parler de tous les autres avantages.

GraphQL : un peu de terminologie

Revenons un instant sur les termes edges et node. Que désignent-ils ? Avec GraphQL, nous parlons, pour une API, de modéliser vos données sous forme de graphe. Nous faisons une représentation visuelle des liens qui existent entre différents ensembles de données.

Parlons un peu de la terminologie de GraphQL et de la façon dont elle vous aidera à travailler efficacement.

Dès que vous utiliserez des listes, vous rencontrerez edges et node en permanence. Revenons un peu en arrière et essayons de définir ces termes.

Dans l’image ci-dessous, vous pouvez voir une version simplifiée de la requête que nous venons de formuler, avec le code dans la partie droite, et une représentation visuelle de l’autre côté. Avec cette requête, nous accédons donc à la QueryRoot et aux produits qui y sont rattachés. Ces produits ont des propriétés. Nous avons demandé le title. Dans la théorie des graphes, ces entités individuelles sont ce que l’on appelle des nœuds (nodes), et les liens qui les relient sont des arêtes (edges).

C’est pour ça que pour accéder à la requête racine et demander des informations sur des QueryRoot, nous devons demander tous les liens qui concernent les QueryRoot. En gros, nous demandons l’ensemble des edges. Ensuite, nous voulons avoir des informations sur les entités qui se trouvent aux extrémités de ces edges. C’est-à-dire sur chaque node.

Vous les verrez constamment si vous effectuez des requêtes multiples, comme pour obtenir les éléments d’une liste. Vous vous habituerez à écrire edges, node, et à obtenir l’information à la fin.

Allons un peu plus loin : parlons des requêtes profondément imbriquées. Nous avons déjà parlé de l’underfetching. Admettons que nous voulions aussi toutes les variantes des 10 premiers produits. Nous pouvons simplement écrire la lettre « V » et la saisie semi-automatique devrait nous proposer variants. Il y a une liste de variants correspondant à products. Nous savons maintenant que nous devons ajouter first, et nous allons indiquer le chiffre 10 de façon totalement arbitraire.

Nous obtenons une liste de variants, et à la fin de ces variants, il y a la variante node. Disons que nous voulons l’ID et le title des variantes. Cliquons à nouveau sur « Play », et voilà ! Là encore, la structure des données retournées calque la structure de notre requête.

Nous avons donc les données, puis products en tant qu’objet, puis edges en tant qu’ensemble d’objets. Chaque nœud contient l’ID et le title comme nous l’avons demandé, et toutes les informations que nous avons demandées concernant la variante : ID et title. Nous pourrions aller plus loin et demander le prix (price) et ainsi de suite. Souvenez-vous que vous pouvez parcourir le schéma pour connaitre les données que l’on peut demander sur les variantes.

Pour revenir à notre représentation visuelle, nous avons simplement repris la même requête et l’avons étirée un peu.

Les produits sont liés aux variantes, donc les nœuds de produits sont liés aux nœuds de variantes. Chaque lien présent dans ce graphe est une arête (edge en anglais). C’est le trait qui relie les nœuds. Les variantes de chaque produit sont au bout de ses arêtes. Dans ce cas, nous nous sommes contentés de deux variantes pour que ce graphe reste lisible.

Pour expliquer notre représentation visuelle par rapport à ce que nous venons de faire en ajoutant les variantes sous les produits, nous avons d’abord demandé les nœuds de produits liés à notre QueryRoot.

Nous savons qu’il existe des liens entre variants et products. À l’intérieur de ces nœuds de produit, il y a donc une connexion avec des variants. Et dans GraphQL, une connexion est une liste de edges. Une edge est une relation entre deux nodes. Au bout de chaque edge, se trouve un node qui contient les champs que nous voulons afficher.

Ces product nodes sont liés aux variant nodes. Chaque trait représente une edge, et ces variants contiennent des noms. Cela signifie que dès que verrez le mot « connection », vous devrez suivre cette structure de edges et nodes pour respecter le modèle sous-jacent de l’API.

Écrire des données avec les mutations dans GraphQL

Nous avons donc parlé des requêtes de données. C’est la première partie de l’équation. Mais nous voulons aussi pouvoir écrire des données.

Comme nous l’avons vu, même si vous enlevez le terme query au début de la partie gauche, c’est implicitement une requête. Mais nous allons maintenant écrire le terme mutation.

Si nous remontons le schéma jusqu’aux types de racines, nous voyons que nous pouvons faire des requêtes (query) ou des mutations (mutation). Intéressons-nous aux types de mutation que nous pouvons effectuer. Comme nous l’avons mentionné, une mutation concerne l’écriture de données, c’est-à-dire la création, l’annulation, la mise à jour et la suppression de données.

Pour nommer une mutation dans Shopify, il faut partir de l’élément qui est la cible de la mutation, là où l’opération aura lieu. Sans parcourir la liste alphabétique du schéma, nous allons simplement écrire la lettre « P ». Nous voyons s’afficher productCreate, productDelete, et productUpdate. Nous allons sélectionner productCreate.

Nous pouvons alors faire défiler les éléments du schéma classés par ordre alphabétique sur la droite de l’écran. Vous pouvez aussi survoler le nom de la requête avec la souris, et simplement cliquer sur le nom qui s’affiche pour atterrir directement sur la définition de cette mutation. C’est très pratique.

Que peut-on lire ? Que cette mutation permet de retourner ProductCreatePayload. Et nous voyons aussi que la mutation contient des arguments. Si vous connaissez l’API REST, vous savez que cela permet, lorsque vous créez un product, d’obtenir toutes les informations qui concernent ce nouveau produit.

Comme pour les requêtes, nous pouvons indiquer de façon précise les données qui nous intéressent. Nous devons écrire product puis les données que nous voulons, comme la date de création, description, title, et ainsi de suite. Le plus important ici, ce sont les arguments. Nous pouvons lire que le type ProductInput ne peut être nul en raison de la présence du point d’exclamation. Il faudra donc l’indiquer. Ensuite, media est un ensemble du type CreateMediaInput qui ne peut être nul. Par contre, l’ensemble lui-même peut être nul, nous n’avons donc pas besoin de l’indiquer. En d’autres mots, nous devons simplement indiquer ce ProductInput.

Comme pour n’importe quel argument, nous allons ouvrir les parenthèses, puis formater ceci en tant qu’objet. Nous allons aussi créer un title pour ce produit : "Awesome Product". Nous allons ouvrir cette mutation pour obtenir notre ProductCreatePayload, qui contient un champ product. À l’intérieur de ce champ product, nous pouvons demander ce qui nous intéresse. Disons que nous voulons l’ID, et juste pour être sûr, le title. Exécutons cette mutation en cliquant sur le bouton « Play ». Vous remarquerez que l’ID est un peu différent si vous avez déjà travaillé avec l’API REST.

Ces ID ne sont pas interchangeables. GraphQL a son propre système d’ID pour désigner les ID. N’essayez pas d’interchanger les ID. Et plus bas, bien sûr, nous obtenons "title": "title": "Awesome Product".

Pour aller plus loin avec GraphQL

Félicitations ! Vous savez désormais faire des requêtes et des mutations sur une boutique Shopify avec GraphiQL. Que pouvez-vous faire pour approfondir vos connaissances sur GraphQL ?

Il y a beaucoup de très bonnes ressources sur le Web pour approfondir GraphQL. Certaines ont été publiées par Shopify. Nous les avons d’ailleurs évoquées dans cet article, notamment le tutoriel pour vous apprendre à formuler votre première requête GraphQL. C’est une excellente ressource pour consolider vos bases, surtout après ce tutoriel. Les mutations et les requêtes qui y sont présentées sont un peu différentes de celles que nous venons de voir, mais les principes restent les mêmes.

Le kit d’apprentissage GraphQL de Shopify est aussi un bon moyen de démarrer si vous voulez travailler avec un client HTTP indépendant. Cet article parle bien de GraphQL et propose un ensemble de requêtes et de mutations préconfigurées pour le client « Insomnia » que vous pouvez télécharger pour travailler sur une boutique. Vous devrez simplement utiliser une clé d’application privée.

Si vous vous intéressez aux kits de développement logiciel d’API Storefront pour accélérer le travail de l’API Storefront, vous pouvez consulter la bibliothèque d’outils de l’API Storefront.

Nous vous recommandons aussi vivement la série de tutoriels « How to GraphQL ». Ils vont beaucoup plus loin que celui-ci et vous trouverez d’excellents tutoriels pratiques pour apprendre à travailler avec des infrastructures logicielles, bibliothèques et langages spécifiques. Par exemple, si vous êtes développeur React et que vous voulez savoir comment utiliser React avec Apollo, une bibliothèque client très populaire, vous trouverez un guide très complet pour vous montrer comment vous y prendre.

Vous pouvez aussi consulter le site officiel GraphQL. La documentation présente les spécificités de GraphQL de façon très claire. C’est donc une excellente ressource pour continuer votre apprentissage.

---

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

Texte original par Chuck Kosman. Traduction par Nicolas Bruno.