Aujourd’hui beaucoup d’API utilisent l’architecture REST. Cet article est une courte introduction à GraphQL, une alternative à REST pour construire une API moderne et robuste.

Mais avant de rentrer dans le vif du sujet, bref retour sur REST !

REST

Créée par Roy Fielding, l’architecture REST (Representational state transfer) est massivement utilisée sur le web. D’ailleurs, vous avez sûrement déjà utilisé ou même développé une API REST. 🤓

Avec REST, le serveur définit un ensemble de ressources que le client peut demander et ces ressources sont accessibles par différentes routes et méthodes. Exemple :

  • Obtenir la liste livres : GET https://monapi.com/books
  • Obtenir un livre : GET  https://monapi.com/book/id
  • Créer un nouveau livre : POST https://monapi.com/book
  • Mettre à jour un livre : PUT https://monapi.com/book/id
  • Supprimer un livre : DELETE https://monapi.com/book/id

Si un client (par exemple, une web app ou un app mobile) souhaite récupérer un livre ayant l’ID 1, le client contacte l’API sur l’adresse https://monapi.com/book/1 avec la méthode GET .

L’API retournera quelque chose comme ça :

{
  id: 1,
  title: "First book",
  description: "Description first book",
  published: true,
  authorId: 7
}

Le client va bien récupérer :

  • l’ID
  • le titre
  • la description
  • l’état du livre (publié ou non)
  • l’id de son auteur.

Les limites de REST

Même si REST est fortement utilisé, il comporte quelques limites.

En voici quelques-unes :

 

  • Des champs fixent sur les retours de l’API

Si vous êtes sur un app mobile, vous n’avez peut-être pas envie d’avoir les mêmes champs qui sont retournés avec la même requête depuis une web app.

Chaque route définie sur le serveur renvoie une liste de champs. Dans notre exemple (comme vu plus haut), si vous souhaitez récupérer un livre, l’API va vous retourner :

  • son ID
  • son titre
  • sa description
  • son état
  • l’ID de l’auteur.

Mais admettons que vous ayez besoin de récupérer seulement l’ID et le titre depuis l’app mobile et non tous les champs comme sur votre web app…

{ 
  id: 1,
  title: "First book", 
  description: "Description first book", 
  published: true, 
  authorId: 7 
}

…et bien l’API va quand même vous retourner la description, l’état du livre et l’ID de l’auteur… alors que vous n’en avez pas besoin. C’est donc une requête plus lourde que nécessaire. 🤔

  • Un appel par route

Si vous souhaitez avoir des informations sur l’auteur du livre, vous allez devoir faire un deuxième appel (par exemple : https://monapi.com/auhor/7) pour récupérer des infos sur l’auteur du livre qui a l’ID 7.

On ne peut pas avoir dans le même appel une demande d’info sur le livre et sur son auteur… 😯

  • La documentation de l’API REST doit être mise à jour

Si vous souhaitez exposer un nouveau champ, par exemple la date de réédition des livres, vous allez devoir penser à bien déclarer ce nouveau champ dans votre documentation (pour que vos collègues soient au courant ! 😉). La mise à jour doit être faite de manière minutieuse.

 

Imaginez si vous pouviez résoudre ces problèmes… Et bien bonne nouvelle. Avec GraphQL, c’est possible !

GraphQL

GraphQL est un langage de requête. Afin de trouver un moyen léger, robuste et rapide pour interroger les données, Facebook a créé GraphQL en 2012. Depuis, le projet est accessible au grand public depuis 2015.

Ces dernières années, GraphQL intéresse de plus en plus de personnes :

Alternative sérieuse à REST, GraphQL permet de résoudre de nombreux problèmes. Notamment ceux cités plus haut.

Mais comment ça marche ?

Récupérer une ressource

Plus besoin de plusieurs routes qui pointent sur des ressources différentes :

  • https://monapi.com/books
  • https://monapi.com/authors
  • …

Avec GraphQL, un seul point d’entrée suffit : l’adresse de votre API https://monapi.com.

En envoyant une seule requête, vous pouvez récupérer directement les données souhaitées :

  • Des infos sur un livre en sélectionnant les champs que nous souhaitons
  • Des champs liés à notre livre, comme l’auteur

Un exemple d’une requête GraphQL :

query {
  livre(id: 1) {
    id
    title
    description
    author {
      first_name
      last_name
    }
  }
}

Au final, l’API retournera quelque chose comme ça :

{
  id: 1,
  title: "First livre"
  description: "Description first livre"
  author {
    first_name: "John",
    last_name: "Doe"
  }
}

Si vous ne voulez pas récupérer la description, il suffit d’enlever le champ description de la requête. Simple.

Votre API va utiliser ce qu’on appelle des resolvers pour faire le lien entre vos ressources si celles-ci sont liées entre elles.

Avec l’exemple ci-dessus, l’API aura dans son resolvers Book, une fonction Author qui va alors utiliser l’id de l’auteur du livre (provenant du champ fk_author_id de la table Book), pour afficher des infos sur l’auteur.

Autre point non négligeable : avec GraphQL, la documentation de votre API est automatiquement générée et mise à jour. ✌️

Ajouter ou modifier une ressource

Avec GraphQL, toujours sur seul point d’entrée https://monapi.com, vous pouvez modifier une ressource.

Pour cela, vous devez utiliser ce qu’on appelle une mutation.

Une mutation est une fonction que vous aurez déclaré sur votre API et qui va se charger de manipuler vos données. Par exemple sur l’API, une fonction createBook va être définie. Elle permettra de créer un nouveau livre :

mutation {
  createBook(
    data: {
      title: "New Book"
      description: "Description new book"
      published: false
      authorId: 7
    }
  ) {
    id
    title
    description
    published
    author {
       first_name
       last_name
    }
  }
}

S’abonner à une ressource

Avec GraphQL, vous pouvez également ajouter des abonnements (subscriptions) sur vos ressources. Si un client souhaite être informé des changements d’une ressource lorsque celle-ci est modifiée, le client en est directement informé. Pratique pour faire du temps réel !

Conclusion

Comme nous l’avons vu précédemment, GraphQL est une sérieuse alternative à REST. Pratique, flexible et robuste, GraphQL permet de monter des API facilement afin de permettre la consommation de ressources de façon rapide et légère.

Pour récupérer une ressource :

  • avec REST : on utilise GET
  • avec GraphQL : on utilise une Query

Pour ajouter ou modifier une ressource :

  • avec REST : on utilise POST , PUT ou DELETE
  • avec GraphQL : on utilise une Mutation

Pour écouter les modifications d’une ressource :

  • avec GraphQL : on utilise une Subscription