L'Admin API, mentionnée depuis le guide 1 de ce parcours, est la porte d'entrée par laquelle votre application accède aux données d'une boutique : produits, commandes, clients. Depuis 2024, Shopify recommande exclusivement GraphQL pour toute nouvelle application ; l'ancienne API REST, que vous croiserez peut-être dans d'anciens tutoriels, est considérée comme historique et ne reçoit plus de nouvelles fonctionnalités. Ce guide vous apprend directement le chemin actuel.

La différence avec une API classique

Avec une API plus traditionnelle, chaque type de donnée dispose généralement de sa propre adresse fixe, qui renvoie toujours le même ensemble d'informations, que vous en ayez besoin ou non. Avec GraphQL, une seule adresse reçoit toutes les requêtes, et c'est vous, dans le corps de la requête, qui précisez exactement quels champs vous voulez recevoir en retour, pas un de plus. Vous obtenez ainsi exactement les données dont votre application a besoin, sans surplus inutile à traiter.

Le vocabulaire de base

Une requête (query) demande à lire des données, sans jamais les modifier. Un champ (field) est une information précise que vous demandez à l'intérieur de cette requête, comme le titre ou le prix d'un produit. Un argument précise ou filtre une demande, par exemple le nombre de résultats à renvoyer. Une mutation, que vous ne pratiquerez pas dans ce guide volontairement limité à la lecture, est l'équivalent d'une requête, mais pour modifier des données plutôt que les lire.

Une première requête : lister des produits

Voici une requête qui demande le titre des cinq premiers produits d'une boutique :

Décryptage : products est le champ principal demandé, avec un argument first: 5 qui limite le résultat aux cinq premiers produits. La structure edges puis node est une convention que vous retrouverez sur presque toute liste de résultats dans l'Admin API : elle permet, entre autres, de parcourir de grandes listes de résultats par pages successives. À l'intérieur de node, vous précisez uniquement les champs qui vous intéressent : ici, id et title, rien de plus.

Ce que la réponse contient

La réponse de Shopify reprend exactement la même forme que votre requête, remplie avec les vraies données : une liste de produits, chacun avec son identifiant et son titre, et rien d'autre que ce que vous avez explicitement demandé. Si vous aviez besoin du prix en plus, il aurait fallu l'ajouter explicitement dans votre requête, comme un champ supplémentaire à l'intérieur de node.

Afficher les produits d'Atelier Lumière dans votre application

Dans le code généré au guide précédent, repérez l'endroit où l'application interroge déjà l'Admin API (le modèle React Router en fournit généralement un exemple prêt à adapter), et modifiez la requête pour qu'elle affiche le titre de vos vrais produits, ceux créés au fil du parcours Shopify : les bases ou directement sur votre dev store. Rechargez l'écran de votre application dans l'administration : les vrais titres doivent apparaître, à la place des données de test.

Une requête sans les bons scopes échoue

Si votre application demande des champs liés aux produits sans avoir déclaré le scope read_products, vu au guide 21, l'Admin API refusera la requête. Une erreur d'autorisation à ce stade n'est presque jamais un problème de syntaxe GraphQL : vérifiez d'abord vos scopes déclarés dans shopify.app.toml avant de chercher ailleurs.

Vérifiez que vous avez compris

Votre requête GraphQL ne demande que le champ title pour chaque produit. Pourrez-vous afficher le prix de ces produits dans votre application sans modifier cette requête ?

Non. Avec GraphQL, vous ne recevez que les champs explicitement demandés dans la requête. Pour afficher un prix, il faut ajouter le champ correspondant directement dans la requête, puis relancer cette requête modifiée : la réponse précédente, sans ce champ, ne contient tout simplement pas cette information.

Chapitre terminé