Introduction à GraphQL

Terminologie et concepts utiles pour utiliser l’API GraphQL d’ARISE.

Schéma

Un schéma définit le système de types d’une API GraphQL. Il décrit l’ensemble complet des données possibles (objets, champs, relations, etc.) auxquelles un client peut accéder. Les requêtes émises par le client sont validées et exécutées par rapport au schéma. Un client peut obtenir des informations sur le schéma par introspection. Un schéma réside sur le serveur de l’API GraphQL.

Champ

Un champ est une unité de données que vous pouvez extraire d’un objet. Comme l’indique la documentation officielle de GraphQL : “Le langage de requête GraphQL consiste essentiellement à sélectionner des champs sur des objets.”

La spécification officielle précise également à propos des champs :

Toutes les opérations GraphQL doivent spécifier leurs sélections jusqu’au niveau des champs qui renvoient des valeurs scalaires afin de garantir une réponse sans ambiguïté.

Cela signifie que si vous essayez de renvoyer un champ qui n’est pas un scalaire, la validation du schéma générera une erreur. Vous devez ajouter des sous-champs imbriqués jusqu’à ce que tous les champs renvoient des scalaires.

Note

Un scalaire désigne un type “simple” comme un string, un booléen ou un entier. Il n’est pas possible de demander à retourner implicitement tous les champs d’un objet. Il faut lister explicitement tous les champs scalaires.

Argument

Un argument est un ensemble de paires clé-valeur associées à un champ spécifique. Certains champs nécessitent un argument. Les mutations nécessitent un objet d’entrée en tant qu’argument.

Héritage

Un schéma GraphQL peut utiliser le terme implements pour définir comment un objet hérite d’une interface.

Voici un exemple fictif de schéma définissant l’interface X et l’objet Y :

interface X {
  unChamp: String!
  unAutreChamp: String!
}

type Y implements X {
  unChamp: String!
  unAutreChamp: String!
  nouveauChamp: 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. (Le signe ! indique que le champ est obligatoire.)

Connexion (Connection)

Les connexions vous permettent d’interroger des objets associés dans le cadre d’un même appel. Grâce aux connexions, vous pouvez utiliser un seul appel GraphQL là où vous auriez dû effectuer plusieurs appels vers une API REST.

Il est utile de le visualiser comme un graphe : des points reliés par des lignes. Les points sont des nœuds, les lignes sont des arêtes. Une connexion définit une relation entre des nœuds.

Arête (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 comporte un champ node et un champ cursor. Les curseurs sont utilisés pour la pagination. Pour plus d’informations, consultez la page sur la Pagination.

Nœud (Node)

Nœud est un terme générique désignant un objet. Vous pouvez rechercher un nœud directement ou accéder à des nœuds associés via une connexion. Si vous spécifiez un node qui ne renvoie pas de scalaire, vous devez inclure des sous-champs jusqu’à ce que tous les champs renvoient des scalaires.

Introspection

GraphQL est introspectif. Cela signifie que vous pouvez interroger un schéma GraphQL pour obtenir des informations le concernant.

• Interrogez __schema pour répertorier tous les types définis dans le schéma et obtenir des détails sur chacun d’entre eux :

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

• Interrogez __type pour obtenir des détails sur n’importe quel type :

query {
  __type(name: "User") {
    name
    kind
    description
    fields {
      name
    }
  }
}