GraphQL : langage de requête et environnement d’exécution pour votre API Web

Les applications Web ont recours à des API (Application Programming Interfaces) pour échanger des données en vue de leur traitement. Pour permettre à d’autres services d’accéder aux données de votre projet Web, vous devez développer et mettre en place une telle interface. Comme partout, il existe ici aussi des standards bien établis, comme SOAP ou REST (Representational State Transfer), qui confèrent à votre API une bonne structure de base, susceptible d’être gérée par n’importe quel langage de programmation. En raison de sa grande simplicité, l’architecture REST est devenue une option très prisée au cours de ces dernières années.

Mais malgré le succès impressionnant de l’architecture REST, il faut savoir reconnaître l’intérêt d’autres options comme GraphQL, parfaitement capables de vous convaincre. Le langage de requête et l’environnement d’exécution de chez Facebook sont à la hauteur de SOAP et de REST, bien que ces derniers présentent certains avantages lorsqu’il s’agit de requêtes plus complexes.

GraphQL est un langage de requête similaire à SQL, conçu par Facebook, qui comprend à la fois un environnement d’exécution et un système de typage. À l’origine, il était uniquement conçu pour être utilisé en interne par la société. Il y avait en effet un besoin de repenser les applications Facebook mobiles, destinées aux environnements iOS et Android, et dont les performances étaient compromises en raison du contexte de plus en plus complexe. En particulier pour la récupération des fils d’actualité, Facebook se devait de trouver une solution adaptée, avec un juste compromis entre le volume d’informations interrogées et le nombre de requêtes-serveur. En 2015, Facebook a laissé libre accès au code source de GraphQL. À cette époque, il permettait de gérer quasiment tous les accès-données des applications mobiles. Depuis 2017, ce projet est disponible sous Licence OWFa-1.0 (Open Web Foundation).

Pour comprendre le fonctionnement de GraphQL, il est important de dissocier les trois composantes essentielles de ce projet open source :

• Un langage de requête : le concept GraphQL est en premier lieu un langage de requête (Query Language) qui offre aux programmes un accès facile aux API. Là où d’autres interfaces d’architectures ne permettent d’exécuter que certaines requêtes pour n’accéder finalement qu’à une quantité limitée de données, les requêtes GraphQL se distinguent par un degré de flexibilité remarquable. Concrètement, il n’y a pas de restrictions dans le nombre de requêtes pouvant être formulées, et vous pouvez définir avec beaucoup de précision les champs de données que vous souhaitez interroger. GraphQL permet de faire à la fois des requêtes en lecture et en écriture, et même des requêtes modifiantes.
• Un système de typage : GraphQL fonctionne d’ailleurs avec son propre système de typage qui vous permet de décrire votre API au moyen de types de données. Les structures de données ainsi définies créent en fait le cadre dans lequel sont exécutées les requêtes. Chaque type est composé d’un ou de plusieurs champ(s) contenant à leur tour leurs propres types. Ce système spécifique ainsi mis en place constitue pour GraphQL un point de repère qui lui permet de valider les requêtes et de réfuter les requêtes contenant des erreurs.
• Un environnement d’exécution : GraphQL offre aussi l’environnement d’exécution serveur qui permet d’exécuter les requêtes GraphQL. Pour ce faire, vous disposez de bibliothèques destinées à divers langages de programmation, comme par exemple Go, Java, JavaScript, PHP, Python et Ruby. Le choix est donc quasiment illimité en ce qui concerne le langage de votre propre API GraphQL. L’environnement d’exécution sert exclusivement à l’analyse syntaxique (Parsen) et à la validation des requêtes, ainsi qu’à la sérialisation des réponses (transformation des objets en un flux d’octets). L’enregistrement et la communication des données (par exemple dans une base de données) sont assurés par votre application web.

En parfaite collaboration, le langage de requêtes, le système de typage et l’environnement d’exécution vous offrent un échafaudage API d’excellente qualité. Ces éléments sont non seulement compatibles avec toutes sortes de plateformes et d’utilisations, mais ils s’adaptent aussi parfaitement aux particularités de votre application Web : vous pouvez donc intégrer l’interface GraphQL dans le code de votre projet, que vous utilisiez le framework Python Django, Ruby Rails ou JavaScript Node.js.

Une des principales caractéristiques de GraphQL est la simplicité du langage de requête, qui facilite de manière remarquable l’accès des développeurs à l’interface. Concernant l’utilisation de GraphQL, nous sommes par exemple surpris de voir la correspondance une à une des réponses par rapport aux requêtes effectuées. Le format des données de réponses est tout aussi simple que celui employé par le très répandu JavaScript JSON (JavaScript Object Notation). L’émission d’une requête très ciblée ne pose aucun problème, à condition que vous connaissiez la structure des données utilisées par votre application. Vous saurez ainsi formuler correctement votre requête. Au-delà de la simplicité des requêtes, GraphQL se distingue aussi par les propriétés suivantes :

• Une structure hiérarchisée : les jeux de données accessibles au moyen des API GraphQL ont une structure hiérarchisée. GraphQL crée automatiquement des relations entre les différents objets, des liens qui facilitent l’exécution (et la réponse) de requêtes plus complexes dans une seule et même requête. Il n’est donc pas nécessaire de prévoir un échange de plusieurs messages entre le Serveur et le Client (ce qu’on appelle aussi des « Round Trips »). La hiérarchie des données se prête particulièrement bien aux bases de données orientées graphes comme JanusGraph et pour les interfaces utilisateurs qui, la plupart du temps, ont aussi une structure hiérarchisée.
• Un typage fort : chaque couche d’une requête GraphQL correspond à un type bien précis, sachant que chaque type permet de décrire un ensemble de champs disponibles. Un tel système de typage est capable de vérifier automatiquement si une requête a été formulée correctement ou non : à l’instar de SQL, grâce à son typage fort, GraphQL est en mesure de vous soumettre déjà pendant le développement, et avant même l’émission de la requête des messages d’erreurs avec des explications claires.
• Une grande flexibilité : GraphQL vous permet de lancer des requêtes en toute flexibilité. Il vous offre ainsi une très grande liberté et beaucoup de souplesse en termes de développement, voire d’adaptation de votre interface. Côté serveur, il ne reste généralement que peu d’ajustements à faire, sachant que l’équipe de développeurs peut agir de manière complètement indépendante, sans se soucier du travail des développeurs côté client. Vous pouvez aussi apporter toutes sortes de modifications et d’extensions à l’API sans gestion de versions, étant donné qu’il est possible d’ajouter sans le moindre problème des champs supplémentaires, sans pour autant impacter les clients existants.

De même qu’il est impossible de nier le très grand succès de REST sur Internet, on ne peut pas faire abstraction de l’option très sérieuse que représente GraphQL dans le domaine de l’architecture des services Web. C’est Facebook qui est à l'initiative du concept et du développement de GraphQL, notamment pour la raison suivante : face à la grande importance et la complexité croissante des applications mobiles Web et en particulier des applications pour Android, iOS etc., GraphQL a su démontrer toute sa puissance en tant que base API ; avec une requête unique, vous pouvez accéder à l’ensemble des données.

L’instance serveur GraphQL délivre exactement les données réclamées par la requête, ce qui permet de n’envoyer ni trop, ni pas assez d’informations au moyen de l’interface. D’autres API REST ne permettent de solliciter qu’un seul jeu de données par requête, et celui-ci est alors généralement délivré dans son intégralité. Dans une comparaison « GraphQL vs. REST », force est de constater que le système de requête de Facebook est beaucoup plus précis et efficace, des avantages dont votre application saura tirer le meilleur profit en termes de performance. Dans la mesure où les utilisateurs d’applications mobiles utilisent souvent des connexions internet plus faibles, ce sont eux qui en profitent généralement au mieux.

Comme vous le voyez, le système de requêtes GraphQL est associé à bien des avantages. Il n’est cependant pas sans poser de sérieux problèmes de sécurité. C’est surtout le cas lorsque vous développez des API ouvertes, dans lesquelles vous ne pouvez pas contrôler les requêtes effectuées par des clients tiers sur les données. Un nombre trop élevé de requêtes peut engendrer un plantage du serveur (intentionnel ou non). Un tel scénario, contre lequel vous devez bien sûr vous protéger, est très fréquent quand vous optez pour une API REST. Il est donc beaucoup plus difficile de mettre en place GraphQL en arrière-plan, tout en garantissant à la fois sa performance et sa sécurité.

L’implémentation d’une procédure de mise en cache des données pour des requêtes non-modifiables avec GraphQL est donc bien plus compliquée que pour des requêtes réalisées dans une interface REST. Ces dernières peuvent être enregistrées provisoirement (par exemple dans le navigateur) grâce à des méthodes de cache de type HTTP.

Avec son offre élargie de bibliothèques prêtes à l’emploi, GraphQL vous permet d’utiliser un grand nombre de langages de programmation. C’est d’ailleurs l’un des principaux avantages de l’implémentation d’une interface GraphQL dans votre application. En tant qu’adepte de Python par exemple, vous pourrez accéder à la librairie graphique ou encore travailler avec la bibliothèque GraphQL java si vous avez un projet en Java. Si votre projet est basé sur l’environnement d’exécution JavaScript Node.js, vous pourrez parfaitement utiliser GraphQL.js comme base d’implémentation.

Dans le tutoriel GraphQL ci-dessous, nous vous présentons, sous la forme d’un exemple, comment débuter avec le framework API à l’aide d’une application JavaScript avec, en plus, le recours à la bibliothèque GraphQL.js et le Web Framework Express.

Pour pouvoir exploiter des bibliothèques GraphQL, vous devez commencer par les installer. Avec la bibliothèque JavaScript GraphQL.js, utilisez le gestionnaire de paquets JavaScript npm (Node Package Manager) et la commande suivante :

Une autre option consiste à utiliser cette bibliothèque en ayant recours au gestionnaire de paquets et de dépendances Yarn (principalement) utilisé par Facebook et par Google :

Dans les deux cas, il est impératif que vous ayez préalablement installé une version de Node.js (version recommandée : Node v6.0.0 ou une version supérieure).

Pour que votre application puisse utiliser des requêtes GraphQL, vous avez besoin d’un schéma qui définisse le type « Query » (donc une requête) ainsi que le point d’accès à votre interface (appelé aussi API-Root) ainsi que la fonction Resolver. Si l’on prend une interface GraphQL à titre d’exemple, qui délivre tout simplement le message « Bonjour tout le monde ! » le code enregistré à cet effet dans le fichier server.js serait le suivant :

Si vous exécutez ce code avec Node.js en tapant la commande

dans le terminal, vous aurez le message suivant :

Après avoir créé une requête simple à l’étape précédente, et l’avoir exécutée au moyen d’une ligne de commande, il est temps maintenant de mettre en place un serveur API GraphQL. Ceci permettra d’accéder à l’interface, par exemple au moyen d’un navigateur internet ordinaire. Pour ce faire, vous allez d’abord installer l’application framework Express citée précédemment, ainsi que la bibliothèque express-GraphQL avec la commande suivante :

Modifiez ensuite l’exemple GraphQL « Bonjour tout le monde ! », pour qu’il constitue la base de votre serveur GraphQL, et non plus un simple script. Pour ce faire, implémentez le module Express et utilisez la bibliothèque express-GraphQL pour connecter le serveur API au point de terminaison HTTP « /GraphQL » :

Comme dans l’exemple GraphQL précédent, ouvrez le fichier server.js avec Node.js, avec pour seule différence, que vous n’exécutez plus cette fois une simple requête, mais que vous démarrez votre serveur API :

Dans le code du serveur Express GraphQL ne figureront pas seulement le schéma et le Root-API : vous y trouverez aussi le point de terminaison HTTP « /GraphQL ». En insérant la commande « graphiql: true » vous activez l’utilitaire du même nom, un programme qui permet d’effectuer des requêtes au moyen d’une interface utilisateur graphique. Pour ce faire, ouvrez votre navigateur, et tapez l’adresse suivante :

Après avoir installé les composants nécessaires durant les différentes étapes de ce tutoriel GraphQL, après avoir créé votre premier schéma de requête et mis en place votre propre serveur, vous pourrez progressivement vous familiariser avec les différentes options permettant de rédiger vos requêtes.

Pour plus de précisions et des explications plus détaillées sur la mise en place de back-ends et front-ends GraphQL, reportez-vous à l’espace tutoriels sur la page officielle du concept API de Facebook.