Guides

GraphQL est un langage de requête pour les API, ainsi qu'un moteur d'exécution qui répond à ces requêtes à partir de vos données. Créé chez Facebook en 2012 et publié en open source en 2015, il offre au client — une interface web, une application mobile ou un autre service — un moyen unique et précis de demander à un serveur exactement les données dont il a besoin, ni plus ni moins. Au lieu que le serveur décide de la forme de chaque réponse, le client décrit ce qu'il veut, et le serveur renvoie des données dans cette même forme.

Cette seule idée est ce qui distingue GraphQL du style REST qui l'a précédé. Avec REST, vous appelez généralement plusieurs points d'accès, chacun renvoyant une structure figée définie à l'avance par le serveur. Avec GraphQL, vous envoyez une seule requête à un seul point d'accès et précisez les champs souhaités ; la réponse reflète votre requête. L'objectif n'est pas de rendre REST obsolète, mais de résoudre des problèmes précis que les points d'accès figés créent à mesure qu'une application et ses données grandissent.

Comment fonctionne GraphQL : le schéma

Au cœur de GraphQL se trouve le schéma, un contrat fortement typé qui décrit chaque type de données disponible et la façon dont ces types sont liés. Parce que le schéma est explicite et typé, les deux parties savent à l'avance ce qui est possible : les outils peuvent valider une requête avant même son exécution, les éditeurs peuvent compléter automatiquement les champs, et la documentation peut être générée automatiquement à partir du schéma. Cette nature auto-descriptive est l'un des avantages les plus concrets de GraphQL.

Une requête GraphQL se lit presque comme le JSON qu'elle renvoie. Vous nommez les champs voulus, imbriquez les champs liés à l'intérieur, et le serveur parcourt le schéma pour résoudre chacun d'eux. Le même point d'accès accepte aussi les mutations, qui modifient les données, et les abonnements (subscriptions), qui permettent au serveur de pousser des mises à jour vers le client via une connexion persistante. Requêtes, mutations et abonnements sont les trois types d'opérations définis par la spécification.

Sur-récupération et sous-récupération

Deux problèmes des points d'accès REST figés expliquent une grande partie de l'attrait de GraphQL : la sur-récupération et la sous-récupération. La sur-récupération, c'est quand un point d'accès renvoie bien plus de données qu'un écran n'en a besoin, gaspillant de la bande passante. La sous-récupération est l'inverse : un seul point d'accès ne renvoie pas assez, obligeant le client à multiplier les allers-retours pour assembler une seule vue. Comme un client GraphQL demande précisément les champs nécessaires en une requête, il évite les deux d'un coup.

• Langage de requête pour API : le client demande exactement les champs voulus
• Schéma fortement typé = auto-documenté, validé, complété automatiquement
• Trois opérations : requêtes (lecture), mutations (écriture), abonnements (push)
• Résout la sur- et la sous-récupération de REST en une seule requête
• Compromis : cache HTTP plus difficile, garde-fous de coût ; REST plus simple pour les petites API

GraphQL et les frameworks front-end

Cette précision est particulièrement utile pour les frameworks front-end comme React, Vue, Svelte et Angular, où un composant a souvent besoin d'une part précise de données. Un composant peut demander exactement les champs qu'il affiche, et à mesure que l'interface évolue, la requête évolue avec elle, sans attendre qu'une équipe back-end crée un nouveau point d'accès. Des bibliothèques clientes matures ajoutent par-dessus le cache, le regroupement des requêtes et la gestion d'état, ce qui explique la popularité de GraphQL dans les front-ends orientés composants.

Les compromis honnêtes

GraphQL n'est pas automatiquement le bon choix, et être honnête sur ses compromis est important. Son point d'accès unique et dynamique rend plus difficile le simple cache HTTP dont profite REST, si bien que le cache migre généralement vers le client ou une couche spécialisée. Des requêtes mal écrites peuvent demander des données profondément imbriquées et surcharger le serveur, c'est pourquoi les API en production ajoutent des limites de profondeur, une analyse de coût et d'autres garde-fous. Pour une petite API aux besoins stables et prévisibles, REST est souvent plus simple et parfaitement suffisant.

Ce que GraphQL n'est pas

Il faut aussi être clair sur ce que GraphQL n'est pas. Ce n'est ni une base de données ni un moteur de stockage : il se place devant vos sources de données existantes — bases de données, API REST ou autres services — et des resolvers vont y chercher les données. Il n'est pas non plus lié à un seul langage ou framework ; serveurs et clients existent dans tout l'écosystème, et la spécification est maintenue par la GraphQL Foundation, neutre vis-à-vis des éditeurs, et non par une seule entreprise.

GraphQL vs REST : comment choisir

Choisir entre GraphQL et REST dépend de la forme de votre application, pas de la mode. GraphQL brille quand de nombreux clients différents ont besoin de parts différentes d'un graphe de données complexe et interconnecté, quand les équipes front-end et back-end veulent avancer indépendamment, ou quand réduire les allers-retours sur des connexions lentes est prioritaire. REST reste un excellent choix par défaut pour les services plus simples, les API publiques qui profitent du cache HTTP, et les équipes qui valorisent son omniprésence et sa simplicité.

En clair, GraphQL est une façon de laisser le client demander exactement les données qu'il veut, décrites par un schéma typé, servies depuis un point d'accès unique. Il ne remplace ni les bases de données, ni REST, ni vos services existants ; il organise la façon dont les clients leur parlent. Savoir quels problèmes il résout — et les coûts de cache et de complexité qu'il introduit — est ce qui vous permet d'y recourir quand il convient vraiment, et de le laisser de côté quand REST est l'outil le mieux adapté.