GraphQL expliqué simplement

GraphQL est un langage de requêtes pour les APIs, conçu par Facebook (les mêmes qui ont inventé React), qui se présente comme une alternative aux API REST.

Pourquoi une alternative à REST ?

Pour comprendre pourquoi GraphQL a été imaginé, il faut d’abord revenir sur ce qui ne fonctionne pas dans les API REST.

Une ressource = une URL

Dans une API REST, chaque ressource nécessite une URL dédiée. Par exemple, si votre application a besoin d’un utilisateur et de ses enfants, il faudra faire deux requêtes distinctes.

Une requête pour récupérer l’utilisateur :

GET /user?id=123

// Réponse
{
   id: 123,
   name: 'Homer',
   children: [456,789]
}

Une requête pour récupérer ses enfants, à partir des données renvoyées par la requête précédente.

GET /users?ids=[456,789]

// Réponse
[
   {
      id: 456,
      name: 'Lisa'
   },
   {
      id: 789,
      name: 'Bart'
   }
]

A cause de son découpage par ressource, REST nous force à démultiplier les appels, et à donc à ralentir le chargement de notre application.

Pas de notion de champ

Pour pallier à ce problème, certains choisissent de détourner les principes du REST, et de retourner toutes les ressources liées en un unique appel.

GET /user?id=123

// Réponse :
{
   id: 123,
   children: [
      {id: 456, name: 'Lisa'}, 
      {id: 789: name: 'Bart'}
   ]
}

Cette façon de faire permet certes de ne pas multiplier les appels, mais elle nous force à toujours recevoir l’intégralité des données, même si notre application n’en a finalement pas besoin.

Tout ceci vient du fait qu’une API REST n’a pas de notion de champs, elle ne connaît que des ressources.

Les principes de GraphQL

Une API GraphQL permet de requêter uniquement les champs souhaités sur les ressources souhaitées, le tout en un seul appel.

// Requête :
POST /
{
    getUser(id: 123) {
        name,
        children: {
            name
        }
     }
}

// Réponse :
{
   name: 'Homer',
   children: [
      {name: 'Lisa'}, 
      {name: 'Bart'}
   ]
}

Dans la requête ci-dessus, nous demandons l’utilisateur 123, avec son nom et celui de ses enfants. Nous devons indiquer dans la requête les informations dont nous avons besoin.

Autre avantage considérable, une API GraphQL met à disposition un schéma, que les applications clientes peuvent récupérer pour connaître les différentes requêtes possibles, ainsi que les différents champs présents dans chaque ressource.

Comparatif REST vs GraphQL

En REST : Une route par ressource.
En GraphQL : Une seule route pour toutes les ressources.

On requête une ressource complète.
On est obligé de précisé les champs souhaités.

Les paramètres sont passés dans l’URL.
Les paramètres sont passés dans le corps de la requête.

La réponse est un objet.
La réponse est un object normalisé, qui correspond au format de la requête.

Les requêtes utilisent les verbes HTTP, comme GET, DELETE, POST, UPDATE.
Les requêtes utilisent uniquement POST (ou uniquement GET).

Illustration

Requête en REST : donne moi l’utilisateur qui a pour nom Simpson et pour prénom Homer.

/user/?lastname=homer&firstname=simpson

Réponse : l’API REST vous renvoie l’utilisateur Homer Simpson avec toutes ses informations, et toutes ses relations.

Requête en GraphQL : donne moi l’utilisateur qui a pour nom Simpson et prénom Homer, donne moi son corps, donne moi sa femme, ainsi que le corps de sa femme.

{
    user(firstname="Homer", lastname="Simpson") {
        body,
        wife {
            body
        }
    }
}

Réponse : En GraphQL, l’API ne renvoie que ce que vous demandez. Dans notre cas, Homer Simpson, son corps, sa femme Marge, et son corps.

Si vous avez besoin de plus d’informations, il vous faut le demander. Notre application n’étant pas naturiste, demandons les habits de nos personnages :

{
    user(firstname="Homer", lastname="Simpson") {
        body,
        clothes,
        wife {
            body
            clothes,
        }
    }
}

J’espère que cet article vous aura permi d’avoir une idée générale de ce qu’est GraphQL et de ses intérêts et avantages. Si vous voulez aller plus loin, je vous recommande ce très complet article de Marmelab.