Connecter React à une API GraphQL

Name: React Développez le Front End de vos applications web et mobiles avec JavaScript
Rating: 5 (2 reviews)

Présentation de GraphQL et premières requêtes

Il y a quelques années, pour appeler une API distante, la référence en termes de moyen technique pour y parvenir était SOAP, avec lequel on encapsulait requêtes et résultats dans de verbeux flux XML. Puis est arrivé REST qui redonnait sa place aux basiques de HTTP et profitait du JSON pour décrire les échanges. Beaucoup plus simple à appréhender que SOAP, les développeurs web notamment n’ont pas mis longtemps à l’adopter.

Aujourd’hui, un nouveau moyen de requêter une API fait parler de lui : GraphQL (http://www.graphql.com/). Explorons ses avantages dans ce chapitre en développant une application React faisant appel à une API GraphQL pour persister des données.

1. Qu’est-ce que GraphQL ?

Pour faire simple, GraphQL est une convention pour échanger des données entre un client (un front-end React par exemple) et un serveur (Node.js, PHP…).

À la base d’une API GraphQL, on trouve donc :

la description des objets pouvant être retournés par une requête : par exemple, un utilisateur comporterait un ID numérique, un nom, une date de naissance, tandis qu’un article aurait comme champs un ID, un titre, un contenu textuel, et une référence vers l’utilisateur l’ayant créé ;
la description des méthodes qui peuvent être appelées sur l’API, avec les paramètres d’entrée de ces méthodes, et la description de ce qu’elles renvoient. Elles-mêmes séparées en deux types :

les queries qui permettent de lire des données ;
les mutations pour créer, mettre à jour ou supprimer des données.

Afin de mieux comprendre ces notions, allons dès maintenant jouer avec une API GraphQL : celle de GitHub.

2. Premières requêtes avec l’API de GitHub

GitHub fournit un outil en ligne pour requêter directement son API GraphQL : son GraphQL API Explorer (https://developer.github.com/v4/explorer/). Sur celui-ci, en haut à droite, cliquez sur le bouton Docs pour ouvrir Documentation...

Création d’une API avec Graphcool

Graphcool (https://www.graph.cool/) est un service proposant de créer une API GraphQL sans écrire la moindre ligne de code. En effet comme nous l’avons vu dans la première section de ce chapitre, GraphQL n’est qu’un langage, la responsabilité de récupérer les données, de les filtrer, de faire les jointures, etc. reste celle du serveur (et donc du développeur).

Graphcool permet de réaliser tout cela de manière automatique, ce qui est idéal pour débuter avec GraphQL, surtout quand le but est comme ici d’aboutir le plus rapidement possible à un front-end travaillant avec l’API.

1. Installation et création du projet Graphcool

Pour le développement, Graphcool se présente comme un outil en ligne de commande que vous pouvez installer avec NPM : npm install -g graphcool. Il propose un moyen d’initialiser rapidement un projet, mais pour faire encore plus simple, créons les fichiers nécessaires à la main avec le strict minimum.

Tout d’abord le fichier package.json :

{ 
 "name": "hello-graphcool", 
 "version": "0.1.0" 
}

Puis le fichier graphcool.yml, manifeste qui indique comment Graphcool va devoir gérer notre application :

# Chemin vers le fichier de définition des types 
# disponibles dans notre API 
types: ./types.graphql 
# Permissions: par défaut tout est accessible à tout le monde 
permissions: 
 - operation: '*'

Et enfin le plus intéressant, le fichier types.graphql, qui permet de définir les types qui seront disponibles dans notre API:

type User @model { 
 id: ID! @isUnique 
 name: String 
}

Il s’agit bien d’un fichier GraphQL, contenant des annotations permettant d’ajouter des informations sur des attributs (@isUnique) ou des types (@model). Une surcouche à GraphQL en quelque sorte : il s’agit du GraphQL Schema Definition Language (https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51).

La magie de Graphcool est de parvenir, à partir de ce fichier, à proposer une API permettant d’interroger une base de données reproduisant les modèles décrits....

Appel d’une API avec React et Apollo Client

À présent que notre API est prête, voyons comment l’appeler, et notamment depuis une application React. Une API GraphQL repose sur une API REST classique, donc il serait bien évidemment possible de l’appeler grâce aux fonctions classiques de requêtes HTTP, par exemple la fonction fetch. Ce serait cependant passer à côté de fonctionnalités très pratiques offertes par GraphQL.

Il existe plusieurs bibliothèques tierces permettant d’appeler une API GraphQL ; la plus connue et la plus réputée dans l’écosystème est probablement Apollo (https://apollographql.com), c’est donc celle-ci que nous allons découvrir ensemble. Apollo permet de réaliser l’intégralité d’une application client-serveur échangeant grâce à GraphQL, mais nous n’allons utiliser que la partie cliente, sobrement appelée Apollo Client (que j’appellerai simplement Apollo dans la suite du chapitre).

Voilà à quoi notre application finale ressemblera

Créons dès maintenant notre projet React, de la même manière que les autres projets, en y ajoutant les dépendances d’Apollo :

yarn init -y 
yarn add -D parcel-bundler 
yarn add react react-dom apollo-boost @apollo/react-hooks graphql

1. Lire des données en envoyant des queries

Pour le moment laissons de côté React pour nous concentrer sur l’appel de notre API, dans le fichier src/index.js. Commençons par créer un objet client qui nous permettra d’effectuer des queries et des mutations. La création de celui-ci nécessite bien entendu l’URI de l’API. Lorsque vous déployez votre API Graphcool via la commande graphcool deploy, l’URL vous est donnée ; il s’agit de l’URL désignée par « Simple API ».

import ApolloClient, { gql } from 'apollo-boost' 
 
const client = new ApolloClient({ 
 uri: 'https://api.graph.cool/simple/v1/...', 
})

Pour effectuer une requête, créons ensuite un objet query en appelant la fonction gql. Notez la syntaxe particulière, nous utilisons une template string pour appeler la fonction : const query...