GraphQL, l'alternative innovante aux APIs REST traditionnelles

Publié le : 02/01/2023 à 12:25

Vous avez sûrement déjà entendu parler de GraphQL, cette spécification de langage de requête qui a révolutionné la façon dont les applications interagissent avec les APIs. Créée par Facebook en 2015, GraphQL est devenue une alternative populaire aux APIs REST traditionnelles et est maintenant largement utilisée par de nombreuses entreprises de toutes tailles.

Mais qu'est-ce que GraphQL exactement et comment peut-elle améliorer votre développement d'API ? Dans cet article, nous allons explorer les concepts de base de GraphQL et voir comment il peut être utilisé pour offrir une flexibilité accrue aux clients, une meilleure gestion des erreurs et un développement plus rapide.

Nous verrons également comment GraphQL peut être utilisé pour prendre en charge plusieurs clients avec une seule API, simplifiant ainsi le développement et la maintenance des applications. Si vous êtes développeur ou responsable technique et que vous souhaitez en savoir plus sur GraphQL et ses avantages, cet article est fait pour vous.

Qu'est-ce que GraphQL ?

GraphQL est une spécification de langage de requête qui permet aux clients de décrire les données qu'ils souhaitent obtenir de l'API (Application Programming Interface).

En utilisant GraphQL, les clients peuvent demander exactement les données dont ils ont besoin, plutôt que de recevoir un ensemble de données prédéterminées. Cela peut être particulièrement utile dans les applications qui ont besoin de beaucoup de données différentes ou qui ont des besoins de données en constante évolution. GraphQL offre également une meilleure gestion des erreurs et un développement plus rapide, car les clients peuvent obtenir toutes les données dont ils ont besoin dans une seule requête.

Pour utiliser GraphQL, vous devez définir un schéma qui décrit les types de données disponibles et les relations entre ces types. Les clients peuvent alors envoyer des requêtes qui décrivent les données qu'ils souhaitent récupérer, en utilisant le langage de requête GraphQL.

Ce langage de requête peut être utilisé avec n'importe quel langage de programmation pour développer un serveur GraphQL ou pour écrire des clients qui interagissent avec un serveur GraphQL existant. Il existe également de nombreux outils et bibliothèques qui facilitent son utilisation.

Pourquoi utiliser GraphQL ?

Flexibilité accrue pour les clients : GraphQL permet aux clients de demander exactement les données dont ils ont besoin, plutôt que de recevoir un ensemble de données prédéterminées. Cela peut être particulièrement utile dans les applications qui ont besoin de beaucoup de données différentes ou qui ont des besoins de données en constante évolution.
Réduction de la surcharge du serveur et une meilleure utilisation des ressources : En ne retournant que les données dont les clients ont besoin, GraphQL peut réduire les demandes de données inutiles et la surcharge du serveur.
Meilleure gestion des erreurs : GraphQL inclut un système de gestion des erreurs détaillé qui permet aux clients de mieux comprendre les problèmes qui se sont produits lors de l'exécution de leur requête.
Développement plus rapide / Performances : GraphQL permet aux clients d'obtenir toutes les données dont ils ont besoin dans une seule requête, ce qui peut accélérer le développement en réduisant le nombre de requêtes nécessaires pour obtenir toutes les données dont une application a besoin.
Prise en charge de plusieurs clients : GraphQL peut être utilisé pour prendre en charge plusieurs clients, tels que des applications mobiles et des sites Web, avec une seule API. Cela peut simplifier le développement et la maintenance des applications.
Sécurité : GraphQL offre un meilleur contrôle de l'accès aux données que REST, car les clients peuvent uniquement accéder aux données auxquelles ils ont été autorisés.
Evolutivité : GraphQL facilite l'ajout et la modification de nouvelles données et de nouvelles fonctionnalités sans perturber les clients existants.

Comment fonctionne GraphQL ?

Comme énoncé précédemment, pour utiliser GraphQL, vous devez d'abord définir un schéma qui décrit les types de données disponibles et les relations entre ces types. Le schéma est écrit en GraphQL Schema Definition Language (SDL). Voici un exemple de schéma qui définit un type User avec deux champs id et name :

type User {
  id: ID!
  name: String!
}

Une fois que le schéma est défini, les clients peuvent envoyer des requêtes GraphQL qui décrivent les données qu'ils souhaitent récupérer. Voici un exemple de requête GraphQL qui récupère un utilisateur avec un ID spécifique :

query {
  user(id: "123") {
    name
  }
}

On peut aussi rendre cela dynamique en passant l'id de l'utilisateur en tant que variable :

query getUser($userId: ID!) {
  user(id: $userId) {
    name
  }
}

Dans mon exemple ci-dessus, mon opération s'appelle getUser et elle prend en paramètre une variable $userId de type ID!. En GraphQL, le ! qui suit un type de données signifie que la valeur est "non nullable", c'est-à-dire qu'elle ne peut pas être null. Si vous tentez de faire une requête en spécifiant une valeur null pour cette variable, vous obtiendrez une erreur.

Le serveur GraphQL exécutera alors la requête et retournera les données demandées au format JSON. Voici un exemple de réponse pour la requête ci-dessus :

{
  "data": {
    "user": {
      "name": "John Doe"
    }
  }
}

GraphQL prend en charge de nombreuses autres fonctionnalités, telles que les mutations (qui permettent aux clients de modifier les données sur le serveur), les souscriptions (qui permettent aux clients de recevoir des notifications en temps réel lorsque les données changent) et les fragments (qui permettent aux clients de réutiliser des parties communes de requêtes).

Ajouter, mettre à jour et supprimer des données grâce aux mutations

Les mutations GraphQL permettent de manipuler les données de votre base de données de manière flexible et sécurisée. Que vous souhaitiez insérer de nouvelles données, mettre à jour des enregistrements existants ou supprimer des données obsolètes, les mutations GraphQL vous offrent toutes les possibilités dont vous avez besoin.

Définissez les mutations dans votre schéma en utilisant le type Mutation. Par exemple pour définir une mutation qui permet d'ajouter un nouvel enregistrement de livre, votre schéma pourrait ressembler à ceci :

type Mutation {
  addBook(title: String!, author: String!): Book
}

type Book {
  id: ID!
  title: String!
  author: String!
}

Envoyez une requête GraphQL qui contient la mutation souhaitée au serveur. Par exemple, pour ajouter un nouveau livre à la base de données, vous pouvez envoyer une requête comme celle-ci :

mutation {
  addBook(
    title: "Le Seigneur des Anneaux",
    author: "J.R.R. Tolkien"
  ) {
    id
    title
    author
  }
}

Traitez la réponse renvoyée par le serveur. Lorsque la mutation est exécutée avec succès, le serveur renvoie généralement les données mises à jour, y compris l'identifiant unique du nouvel enregistrement (si applicable). Vous pouvez utiliser ces données pour mettre à jour votre application ou afficher une notification à l'utilisateur. Si la mutation échoue, le serveur peut renvoyer une erreur avec des informations sur ce qui s'est passé.

Les mutations GraphQL nécessitent généralement une authentification et une autorisation préalables pour être exécutées. Assurez-vous de mettre en place un système de gestion de l'accès adéquat avant d'utiliser des mutations dans votre application.

Quels sont les inconvénients de GraphQL ?

Complexité de mise en œuvre : GraphQL nécessite une architecture de serveur différente de celle utilisée pour les API REST traditionnelles, ce qui peut être complexe à mettre en place et à maintenir.
Manque de documentation et de ressources : bien que GraphQL soit de plus en plus populaire, il y a encore relativement peu de documentation et de ressources disponibles par rapport à d'autres technologies. Cela peut rendre difficile la recherche de solutions aux problèmes courants.
Manque de prise en charge des outils : bien que de nombreux outils prennent en charge GraphQL, ils ne sont pas aussi largement disponibles que ceux pour les API REST traditionnelles.
Performance : bien que GraphQL offre une grande flexibilité en ce qui concerne les requêtes que vous pouvez effectuer, cela peut entraîner des problèmes de performance si vous n'êtes pas attentif à la façon dont vous construisez vos requêtes.
Sécurité : bien que GraphQL offre une meilleure sécurité que REST en termes de contrôle de l'accès aux données, il peut être plus difficile de mettre en œuvre des mesures de sécurité avancées telles que l'authentification et l'autorisation.

Il est important de peser ces inconvénients contre les avantages potentiels de GraphQL avant de décider s'il convient à votre projet.

Comment utiliser GraphQL ?

Vous pouvez utiliser GraphQL avec n'importe quel langage de programmation pour développer un serveur GraphQL ou pour écrire des clients qui interagissent avec un serveur GraphQL existant. Il existe également de nombreux outils et bibliothèques qui facilitent l'utilisation de GraphQL.

Pour l'utiliser, vous devez d'abord créer un serveur GraphQL qui sera chargé de traiter les requêtes et les mutations envoyées par les clients.

Voici les étapes de base pour créer un serveur GraphQL :

Installez les dépendances nécessaires. Vous aurez besoin d'un framework de serveur GraphQL, comme express-graphql ou apollo-server, et d'une bibliothèque GraphQL telle que graphql ou graphql-js. Vous pouvez les installer en utilisant un gestionnaire de paquets comme npm ou yarn.
Définissez votre schéma GraphQL. Vous devez décrire les types de données disponibles et les relations entre ces types en utilisant le langage GraphQL Schema Definition (GLSD). Vous pouvez définir votre schéma en dur dans votre code ou en le chargeant à partir d'un fichier.
Écrivez les resolvers. Les resolvers sont des fonctions qui sont appelées chaque fois que GraphQL reçoit une requête ou une mutation et qui sont responsables de la récupération ou de la modification des données appropriées. Vous devez écrire un resolver pour chaque champ de votre schéma qui nécessite de récupérer ou de modifier des données.
Créez un serveur GraphQL en utilisant le framework et la bibliothèque choisis. Vous devez spécifier votre schéma et vos resolvers lors de la création du serveur. Vous pouvez également configurer d'autres options, telles que les headers HTTP autorisés ou les méthodes d'authentification.
Lancez le serveur et testez-le en envoyant des requêtes et des mutations à partir de votre client GraphQL. Vous pouvez utiliser un outil de développement GraphQL, comme GraphiQL ou Insomnia, pour envoyer des requêtes et visualiser les réponses.

Il existe également de nombreux frameworks et bibliothèques qui facilitent la création d'un serveur GraphQL, en offrant des fonctionnalités telles que la génération de schéma à partir de modèles de données ou la gestion de la persistence des données. Ces frameworks peuvent vous faire gagner du temps et vous permettre de vous concentrer sur le développement de votre application plutôt que sur la gestion des détails techniques de GraphQL.

Il est aussi recommandé de mettre en place une stratégie de gestion des erreurs pour votre serveur GraphQL. Vous pouvez utiliser des middlewares ou des intercepteurs d'erreurs pour gérer les erreurs de manière centralisée et renvoyer des réponses d'erreur cohérentes aux clients en cas de problème.

Enfin, n'oubliez pas de tester et de déboguer votre serveur GraphQL pour vous assurer qu'il fonctionne correctement et qu'il répond aux besoins de votre application. Vous pouvez utiliser des outils de test tels que Jest ou Mocha pour écrire des tests unitaires et de l'intégration pour votre serveur GraphQL.

Améliorer la gestion des erreurs avec GraphQL : conseils et bonnes pratiques

La gestion des erreurs est une partie importante de tout projet de développement, et cela est particulièrement vrai lorsque vous utilisez GraphQL. En effet, GraphQL vous permet de faire des demandes très précises pour les données que vous souhaitez récupérer, ce qui peut entraîner de nombreux cas d'erreur potentiels.

Il est donc essentiel de mettre en place une stratégie de gestion des erreurs efficace pour votre serveur GraphQL. Cela vous permettra de renvoyer des réponses d'erreur cohérentes aux clients en cas de problème, ce qui peut aider à améliorer l'expérience utilisateur et à faciliter le développement de votre application.

Voici quelques conseils pour améliorer la gestion des erreurs avec GraphQL :

Utilisez les codes d'erreur standard GraphQL. GraphQL a défini une liste de codes d'erreur standard qui peuvent être utilisés pour indiquer le type d'erreur qui s'est produite. En utilisant ces codes, vous pouvez facilement identifier et traiter les erreurs courantes, telles que l'accès non autorisé ou la validation des données.
Renvoyez des messages d'erreur clairs et descriptifs aux clients. Les messages d'erreur doivent être suffisamment détaillés pour que les clients puissent comprendre ce qui s'est passé et comment résoudre le problème. N'oubliez pas de masquer les détails sensibles ou techniques qui ne sont pas pertinents pour les clients.
Gérez les erreurs de manière centralisée. Vous pouvez utiliser des middlewares ou des intercepteurs d'erreurs pour gérer les erreurs de manière centralisée et renvoyer des réponses d'erreur cohérentes aux clients en cas de problème. Cela peut vous aider à maintenir un code plus propre et plus facile à maintenir.
Testez et déboguez votre serveur GraphQL. Assurez-vous de tester votre serveur GraphQL pour vous assurer qu'il gère correctement les erreurs et qu'il renvoie les codes d'erreur et les messages appropriés aux clients. Vous pouvez utiliser des outils de test tels que Jest ou Mocha pour écrire des tests unitaires et de l'intégration pour votre serveur GraphQL. Cela vous permettra de vous assurer que votre serveur répond de manière cohérente et prévisible en cas d'erreur, ce qui peut vous aider à éviter les problèmes lors de la mise en production.

Il est également important de déboguer votre serveur GraphQL en cas de problème. Vous pouvez utiliser des outils tels que GraphiQL ou Insomnia pour envoyer des requêtes et des mutations de test et visualiser les réponses de votre serveur. Cela peut vous aider à identifier les problèmes et à trouver des solutions rapidement.

En résumé, la gestion des erreurs est une partie cruciale de tout projet GraphQL. En suivant ces conseils et en mettant en place une stratégie de gestion des erreurs efficace, vous pourrez offrir une expérience utilisateur de qualité et faciliter le développement de votre application.

Exemple concret

Vous pouvez consulter un exemple de dépôt disponible sur GitHub que j'ai personnellement créé. Il met en place un serveur GraphQL avec Apollo Server 4 et TypeScript. Le lien pour y accéder : https://github.com/valentin-harrang/apollo-server.