Présentation de GraphQL

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" http(s)://HOSTNAME/api/graphql
```
Remarque : s vous obtenez la réponse "message": "Bad credentials" ou 401 Unauthorized, vérifiez que vous utilisez un jeton valide. Si vous recevez une erreur 403 avec Resource 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" \
http(s)://HOSTNAME/api/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 est POST, 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 ».

Dans cet article