GraphQL

Qu'est-ce que GraphQL ?

GraphQL est un langage de requête pour les API et un environnement d'exécution qui traite ces requêtes. Un serveur publie un schéma fortement typé, et le client envoie une requête qui nomme exactement les champs voulus. La réponse reprend la forme de la requête. Contrairement à une API REST classique, un service GraphQL est généralement servi depuis une seule URL, souvent /graphql. Le langage est défini dans la spécification GraphQL.

Comment fonctionne GraphQL

Schéma et opérations

Le schéma décrit les types et les champs qu'un client peut demander. Il existe trois types d'opération : une query lit des données, une mutation modifie des données et déclenche des effets de bord, et une subscription livre des mises à jour en temps réel. Les requêtes peuvent utiliser des arguments, des variables, des alias et des fragments, et la validation rejette une requête non conforme au schéma avant son exécution. Les resolvers produisent ensuite les données de chaque champ.

Une requête, une forme de réponse

Une requête sur le nom et l'e-mail d'un utilisateur ne renvoie que ces deux champs sous la clé data de premier niveau. En cas de problème, la réponse contient une clé errors. Une requête est normalement un POST HTTP avec un corps JSON contenant query, operationName et variables. Un serveur peut aussi accepter GET, mais uniquement pour les requêtes de lecture, jamais pour les mutations. Les détails se trouvent dans servir GraphQL via HTTP.

Introspection

L'introspection permet à un client d'interroger le schéma lui-même, via des champs comme __schema et __type. Elle alimente les navigateurs de documentation et l'autocomplétion des éditeurs. La documentation de GraphQL précise que les API utilisées uniquement par vos propres applications n'en ont souvent pas besoin en production, et que la désactiver est courant parce que cela réduit la surface d'attaque.

Exemple

Un écran mobile a besoin du nom d'un produit et de ses trois derniers avis. Avec REST, cela peut représenter un appel pour le produit et un autre pour les avis. Avec GraphQL, le client envoie une seule requête product(id: "42") { name reviews(first: 3) { text } } et reçoit exactement cela. Le compromis se déplace vers le serveur, qui doit résoudre efficacement chaque champ imbriqué.

Erreurs fréquentes et compromis

• Le problème N+1. Résoudre une liste d'éléments puis chercher des données liées pour chacun déclenche un appel backend supplémentaire par élément. Le regroupement, par exemple avec DataLoader, rassemble ces recherches en une seule requête.
• Requêtes sans limite. Comme le client façonne la requête, une requête très imbriquée ou très large peut charger fortement le serveur. Paginez les champs de liste (pagination d'API) et utilisez des limites de profondeur, de largeur et de complexité, ainsi que des délais d'expiration.
• Cache HTTP plus faible. REST donne à chaque ressource une URL que les caches HTTP comprennent. GraphQL n'a pas cette identité intégrée : l'API devrait donc exposer un id unique global que les clients peuvent utiliser pour bâtir un cache. Voir le cache d'API.
• Croire que HTTP 200 veut dire succès. Une réponse avec des données peut tout de même contenir errors, et HTTP n'a pas de statut pour un succès partiel. Vérifiez le corps, pas seulement le code de statut.
• Laisser la sécurité au seul schéma. L'authentification, l'autorisation et les limites d'opération restent nécessaires. Lisez la sécurité des API.

GraphQL, tests de charge et surveillance d'API

Chaque opération GraphQL est une requête HTTP vers un endpoint : un resolver lent ou un motif N+1 se voit donc dans le temps de réponse sous charge, pas dans une URL qui échoue. Utilisez des tests de charge avec des requêtes réalistes, car une requête légère et une requête coûteuse partagent la même URL. Pour les contrôles continus, la FAQ de la surveillance d'API indique que GraphQL est pris en charge comme un POST avec un corps JSON. Ajoutez une assertion sur le corps de la réponse pour qu'un 200 contenant errors fasse quand même échouer le contrôle, et voyez ce qu'est la surveillance d'API. À lire aussi : 10 problèmes de performance d'API courants et comment les détecter et comment la surveillance d'API aide votre entreprise.

Questions fréquentes (FAQ)

GraphQL est-il une base de données ?

Non. GraphQL est un langage de requête et un environnement d'exécution pour les API. Il se place devant vos sources de données existantes, comme les bases de données, les services et d'autres API, et les resolvers décident d'où vient chaque champ.

Quelle est la différence entre GraphQL et REST ?

REST expose de nombreuses URL, chacune renvoyant une forme de ressource fixe. GraphQL expose généralement un seul endpoint où le client choisit les champs. GraphQL réduit la sur-récupération de données, mais déplace davantage de travail et de complexité de cache côté serveur.

GraphQL utilise-t-il POST pour tout ?

Les requêtes et les mutations sont normalement envoyées en POST avec un corps JSON. Le guide sur le service via HTTP autorise GET uniquement pour les requêtes de lecture, et les mutations doivent utiliser POST.

Faut-il désactiver l'introspection en production ?

Pour les API utilisées uniquement par vos propres applications, elle n'est généralement pas nécessaire en production, et la désactiver est courant. Ce n'est qu'un volet d'une approche plus large qui comprend l'authentification, l'autorisation, les limites de profondeur et l'analyse de coût.

Puis-je surveiller une API GraphQL avec LoadFocus ?

La page de surveillance d'API de LoadFocus indique que GraphQL est pris en charge comme un POST avec un corps JSON. Ajoutez une assertion sur le corps pour détecter les erreurs renvoyées avec un statut 200.