Terminologie GraphQL
L’API GraphQL GitHub représente un changement architectural et conceptuel de l’API REST GitHub. Vous rencontrerez probablement une nouvelle terminologie dans les documents de référence de l’API GraphQL.
schéma
Un schéma définit le système type de l’API GraphQL. Il décrit l’ensemble complet de données possibles (objets, champs, relations, tout) auquel un client peut accéder. Les appels du client sont validés et exécutés sur le schéma. Un client peut trouver des informations sur le schéma via l’introspection. Un schéma réside sur le serveur de l’API GraphQL. Pour plus d’informations, consultez « Découverte de l’API GraphQL ».
Champ
Un champ est une unité de données que vous pouvez récupérer à partir d’un objet. Comme il est indiqué dans les documents GraphQL officiels : « Le langage de requête GraphQL est essentiellement destiné à la sélection des champs sur des objets ».
La spécification officielle dit également sur les champs :
Toutes les opérations GraphQL doivent spécifier leurs sélections vers les champs qui retournent des valeurs scalaires pour garantir une réponse sans ambiguïté.
Cela signifie que si vous essayez de retourner un champ qui n’est pas scalaire, la validation du schéma lève une erreur. Vous devez ajouter des sous-champs imbriqués jusqu’à ce que tous les champs retournent des scalaires.
Argument
Un argument est un ensemble de paires clé-valeur attachées à un champ spécifique. Certains champs nécessitent un argument. Les mutations nécessitent un objet d’entrée comme argument.
Implémentation
Un schéma GraphQL peut utiliser le terme implémentations pour définir la façon dont un objet hérite d’une interface.
Voici un exemple fictif de schéma qui définit l’interface X
et l’objet Y
:
interface X {
some_field: String!
other_field: String!
}
type Y implements X {
some_field: String!
other_field: String!
new_field: String!
}
Cela signifie que l’objet Y
nécessite les mêmes champs/arguments/types de retour que l’interface X
, tout en ajoutant de nouveaux champs spécifiques à l’objet Y
. (!
signifie que le champ est requis.)
Dans les documents de référence, vous trouverez ce qui suit :
-
Chaque objet répertorie les interfaces dont il hérite sous Implémentations.
-
Chaque interface répertorie les objets qui héritent de celui-ci sous Implémentations.
Connexion
Les connexions vous permettent d’interroger des objets associés dans le cadre du même appel. Avec les connexions, vous pouvez utiliser un seul appel GraphQL où vous devrez utiliser plusieurs appels vers une API REST. Pour plus d’informations, consultez « Migration de REST vers GraphQL ».
Il est utile d’imager un graphique : points connectés par des lignes. Les points sont des nœuds, les lignes sont des arêtes. Une connexion définit une relation entre les nœuds.
Edge
Les arêtes représentent les connexions entre les nœuds. Lorsque vous interrogez une connexion, vous parcourez ses arêtes pour accéder à ses nœuds. Chaque champ edges
a un champ node
et un champ cursor
. Les curseurs sont utilisés pour la pagination. Pour plus d’informations, consultez « Utilisation de la pagination dans l’API GraphQL ».
Nœud
Noeud est un terme générique pour un objet. Vous pouvez rechercher un nœud directement ou accéder aux nœuds associés via une connexion. Si vous spécifiez un node
qui ne retourne pas de scalaire, vous devez inclure des sous-champs jusqu’à ce que tous les champs retournent des scalaires. Pour plus d’informations sur l’accès aux ID de nœud via l’API REST et leur utilisation dans les requêtes GraphQL, consultez « Utilisation d’ID de nœud globaux ».
Découverte de l’API GraphQL
GraphQL est introspectif. Cela signifie que vous pouvez interroger un schéma GraphQL pour plus d’informations sur lui-même.
-
Requête
__schema
pour répertorier tous les types définis dans le schéma et obtenir des détails sur chacun d’eux :query { __schema { types { name kind description fields { name } } } }
-
Requête
__type
pour obtenir des détails sur n’importe quel type :query { __type(name: "Repository") { name kind description fields { name } } }
-
Vous pouvez également exécuter une requête d’introspection du schéma via une requête
GET
:curl -H "Authorization: bearer TOKEN" https://api.github.com/graphql
Remarque : s vous obtenez la réponse
"message": "Bad credentials"
ou401 Unauthorized
, vérifiez que vous utilisez un jeton valide. Si vous recevez une erreur403
avecResource not accessible by personal access token
, assurez-vous que votre fine-grained personal access token est ciblé sur le bon propriétaire de ressource. Par exemple, il doit cibler l’organisation propriétaire du dépôt auquel vous essayez d’accéder.Les résultats sont au format JSON, nous vous recommandons donc de les imprimer pour faciliter la lecture et la recherche. Vous pouvez utiliser un outil de ligne de commande tel que jq ou diriger les résultats dans
python -m json.tool
dans ce but.Vous pouvez également transmettre le type de média
idl
pour renvoyer les résultats au format IDL, qui est une version condensée du schéma :$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \ https://api.github.com/graphql
Remarque : la requête d’introspection est probablement la seule requête
GET
que vous allez exécuter dans GraphQL. Si vous transmettez un corps, la méthode de requête GraphQL estPOST
, qu’il s’agisse d’une requête ou d’une mutation.Pour plus d’informations sur l’exécution de requêtes, consultez « Formation d’appels avec GraphQL ».