GraphQL : langage de requête et en­vi­ron­ne­ment d’exécution pour votre API Web

Les ap­pli­ca­tions Web ont recours à des API (Ap­pli­ca­tion Pro­gram­ming In­ter­faces) pour échanger des données en vue de leur trai­te­ment. Pour permettre à d’autres services d’accéder aux données de votre projet Web, vous devez dé­ve­lop­per et mettre en place une telle interface. Comme partout, il existe ici aussi des standards bien établis, comme SOAP ou REST (Repre­sen­ta­tio­nal State Transfer), qui confèrent à votre API une bonne structure de base, sus­cep­tible d’être gérée par n’importe quel langage de pro­gram­ma­tion. En raison de sa grande sim­pli­cité, l’ar­chi­tec­ture REST est devenue une option très prisée au cours de ces dernières années.

Mais malgré le succès im­pres­sion­nant de l’ar­chi­tec­ture REST, il faut savoir re­con­naître l’intérêt d’autres options comme GraphQL, par­fai­te­ment capables de vous con­vaincre. Le langage de requête et l’en­vi­ron­ne­ment d’exécution de chez Facebook sont à la hauteur de SOAP et de REST, bien que ces derniers pré­sen­tent 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 en­vi­ron­ne­ment d’exécution et un système de typage. À l’origine, il était uni­que­ment conçu pour être utilisé en interne par la société. Il y avait en effet un besoin de repenser les ap­pli­ca­tions Facebook mobiles, destinées aux en­vi­ron­ne­ments iOS et Android, et dont les per­for­mances étaient com­pro­mises en raison du contexte de plus en plus complexe. En par­ti­cu­lier pour la ré­cu­pé­ra­tion des fils d’actualité, Facebook se devait de trouver une solution adaptée, avec un juste compromis entre le volume d’in­for­ma­tions in­ter­ro­gées et le nombre de requêtes-serveur. En 2015, Facebook a laissé libre accès au code source de GraphQL. À cette époque, il per­met­tait de gérer quasiment tous les accès-données des ap­pli­ca­tions mobiles. Depuis 2017, ce projet est dis­po­nible sous Licence OWFa-1.0 (Open Web Foundation).

Pour com­prendre le fonc­tion­ne­ment de GraphQL, il est important de dissocier les trois com­po­santes es­sen­tielles 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 pro­grammes un accès facile aux API. Là où d’autres in­ter­faces d’ar­chi­tec­tures ne per­met­tent d’exécuter que certaines requêtes pour n’accéder fi­na­le­ment qu’à une quantité limitée de données, les requêtes GraphQL se dis­tin­guent par un degré de flexi­bi­lité re­mar­quable. Con­crè­te­ment, il n’y a pas de res­tric­tions 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 in­ter­ro­ger. GraphQL permet de faire à la fois des requêtes en lecture et en écriture, et même des requêtes mo­di­fiantes.
• Un système de typage : GraphQL fonc­tionne 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 struc­tures 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é­ci­fique 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 en­vi­ron­ne­ment d’exécution : GraphQL offre aussi l’en­vi­ron­ne­ment d’exécution serveur qui permet d’exécuter les requêtes GraphQL. Pour ce faire, vous disposez de bi­blio­thèques destinées à divers langages de pro­gram­ma­tion, comme par exemple Go, Java, Ja­vaS­cript, PHP, Python et Ruby. Le choix est donc quasiment illimité en ce qui concerne le langage de votre propre API GraphQL. L’en­vi­ron­ne­ment d’exécution sert ex­clu­si­ve­ment à l’analyse syn­taxique (Parsen) et à la va­li­da­tion des requêtes, ainsi qu’à la sé­ria­li­sa­tion des réponses (trans­for­ma­tion des objets en un flux d’octets). L’en­re­gis­tre­ment et la com­mu­ni­ca­tion des données (par exemple dans une base de données) sont assurés par votre ap­pli­ca­tion web.

En parfaite col­la­bo­ra­tion, le langage de requêtes, le système de typage et l’en­vi­ron­ne­ment d’exécution vous offrent un écha­fau­dage API d’ex­cel­lente qualité. Ces éléments sont non seulement com­pa­tibles avec toutes sortes de pla­te­formes et d’uti­li­sa­tions, mais ils s’adaptent aussi par­fai­te­ment aux par­ti­cu­la­ri­tés de votre ap­pli­ca­tion 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 Ja­vaS­cript Node.js.

Une des prin­ci­pales ca­rac­té­ris­tiques de GraphQL est la sim­pli­cité du langage de requête, qui facilite de manière re­mar­quable l’accès des dé­ve­lop­peurs à l’interface. Con­cer­nant l’uti­li­sa­tion de GraphQL, nous sommes par exemple surpris de voir la cor­res­pon­dance une à une des réponses par rapport aux requêtes ef­fec­tuées. Le format des données de réponses est tout aussi simple que celui employé par le très répandu Ja­vaS­cript JSON (Ja­vaS­cript Object Notation). L’émission d’une requête très ciblée ne pose aucun problème, à condition que vous con­nais­siez la structure des données utilisées par votre ap­pli­ca­tion. Vous saurez ainsi formuler cor­rec­te­ment votre requête. Au-delà de la sim­pli­cité des requêtes, GraphQL se distingue aussi par les pro­prié­tés suivantes :

• Une structure hié­rar­chi­sée : les jeux de données ac­ces­sibles au moyen des API GraphQL ont une structure hié­rar­chi­sée. GraphQL crée au­to­ma­ti­que­ment des relations entre les dif­fé­rents objets, des liens qui fa­ci­li­tent 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é­ces­saire de prévoir un échange de plusieurs messages entre le Serveur et le Client (ce qu’on appelle aussi des « Round Trips »). La hié­rar­chie des données se prête par­ti­cu­liè­re­ment bien aux bases de données orientées graphes comme Ja­nus­Graph et pour les in­ter­faces uti­li­sa­teurs qui, la plupart du temps, ont aussi une structure hié­rar­chi­sée.
• Un typage fort : chaque couche d’une requête GraphQL cor­res­pond à un type bien précis, sachant que chaque type permet de décrire un ensemble de champs dis­po­nibles. Un tel système de typage est capable de vérifier au­to­ma­ti­que­ment si une requête a été formulée cor­rec­te­ment ou non : à l’instar de SQL, grâce à son typage fort, GraphQL est en mesure de vous soumettre déjà pendant le dé­ve­lop­pe­ment, et avant même l’émission de la requête des messages d’erreurs avec des ex­pli­ca­tions claires.
• Une grande flexi­bi­lité : GraphQL vous permet de lancer des requêtes en toute flexi­bi­lité. Il vous offre ainsi une très grande liberté et beaucoup de souplesse en termes de dé­ve­lop­pe­ment, voire d’adap­ta­tion de votre interface. Côté serveur, il ne reste gé­né­ra­le­ment que peu d’ajus­te­ments à faire, sachant que l’équipe de dé­ve­lop­peurs peut agir de manière com­plè­te­ment in­dé­pen­dante, sans se soucier du travail des dé­ve­lop­peurs côté client. Vous pouvez aussi apporter toutes sortes de mo­di­fi­ca­tions et d’ex­ten­sions à l’API sans gestion de versions, étant donné qu’il est possible d’ajouter sans le moindre problème des champs sup­plé­men­taires, sans pour autant impacter les clients existants.

De même qu’il est im­pos­sible de nier le très grand succès de REST sur Internet, on ne peut pas faire abs­trac­tion de l’option très sérieuse que re­pré­sente GraphQL dans le domaine de l’ar­chi­tec­ture des services Web. C’est Facebook qui est à l'ini­tia­tive du concept et du dé­ve­lop­pe­ment de GraphQL, notamment pour la raison suivante : face à la grande im­por­tance et la com­plexité crois­sante des ap­pli­ca­tions mobiles Web et en par­ti­cu­lier des ap­pli­ca­tions 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 exac­te­ment les données réclamées par la requête, ce qui permet de n’envoyer ni trop, ni pas assez d’in­for­ma­tions au moyen de l’interface. D’autres API REST ne per­met­tent de sol­li­ci­ter qu’un seul jeu de données par requête, et celui-ci est alors gé­né­ra­le­ment délivré dans son in­té­gra­lité. Dans une com­pa­rai­son « 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 ap­pli­ca­tion saura tirer le meilleur profit en termes de per­for­mance. Dans la mesure où les uti­li­sa­teurs d’ap­pli­ca­tions mobiles utilisent souvent des con­nexions internet plus faibles, ce sont eux qui en profitent gé­né­ra­le­ment 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é­ve­lop­pez des API ouvertes, dans les­quelles vous ne pouvez pas contrôler les requêtes ef­fec­tuées par des clients tiers sur les données. Un nombre trop élevé de requêtes peut engendrer un plantage du serveur (in­ten­tion­nel 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 ga­ran­tis­sant à la fois sa per­for­mance et sa sécurité.

L’im­plé­men­ta­tion d’une procédure de mise en cache des données pour des requêtes non-mo­di­fiables avec GraphQL est donc bien plus com­pli­quée que pour des requêtes réalisées dans une interface REST. Ces dernières peuvent être en­re­gis­trées pro­vi­soi­re­ment (par exemple dans le na­vi­ga­teur) grâce à des méthodes de cache de type HTTP.

Avec son offre élargie de bi­blio­thèques prêtes à l’emploi, GraphQL vous permet d’utiliser un grand nombre de langages de pro­gram­ma­tion. C’est d’ailleurs l’un des prin­ci­paux avantages de l’im­plé­men­ta­tion d’une interface GraphQL dans votre ap­pli­ca­tion. En tant qu’adepte de Python par exemple, vous pourrez accéder à la librairie graphique ou encore tra­vail­ler avec la bi­blio­thèque GraphQL java si vous avez un projet en Java. Si votre projet est basé sur l’en­vi­ron­ne­ment d’exécution Ja­vaS­cript Node.js, vous pourrez par­fai­te­ment utiliser GraphQL.js comme base d’im­plé­men­ta­tion.

Dans le tutoriel GraphQL ci-dessous, nous vous pré­sen­tons, sous la forme d’un exemple, comment débuter avec le framework API à l’aide d’une ap­pli­ca­tion Ja­vaS­cript avec, en plus, le recours à la bi­blio­thèque GraphQL.js et le Web Framework Express.

Pour pouvoir exploiter des bi­blio­thèques GraphQL, vous devez commencer par les installer. Avec la bi­blio­thèque Ja­vaS­cript GraphQL.js, utilisez le ges­tion­naire de paquets Ja­vaS­cript npm (Node Package Manager) et la commande suivante :

Une autre option consiste à utiliser cette bi­blio­thèque en ayant recours au ges­tion­naire de paquets et de dé­pen­dances Yarn (prin­ci­pa­le­ment) utilisé par Facebook et par Google :

Dans les deux cas, il est impératif que vous ayez préa­la­ble­ment installé une version de Node.js (version re­com­man­dée : Node v6.0.0 ou une version su­pé­rieure).

Pour que votre ap­pli­ca­tion 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 sim­ple­ment le message « Bonjour tout le monde ! » le code en­re­gis­tré à 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 main­te­nant de mettre en place un serveur API GraphQL. Ceci permettra d’accéder à l’interface, par exemple au moyen d’un na­vi­ga­teur internet ordinaire. Pour ce faire, vous allez d’abord installer l’ap­pli­ca­tion framework Express citée pré­cé­dem­ment, ainsi que la bi­blio­thè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, im­plé­men­tez le module Express et utilisez la bi­blio­thèque express-GraphQL pour connecter le serveur API au point de ter­mi­nai­son HTTP « /GraphQL » :

Comme dans l’exemple GraphQL précédent, ouvrez le fichier server.js avec Node.js, avec pour seule dif­fé­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 fi­gu­re­ront pas seulement le schéma et le Root-API : vous y trouverez aussi le point de ter­mi­nai­son HTTP « /GraphQL ». En insérant la commande « graphiql: true » vous activez l’uti­li­taire du même nom, un programme qui permet d’effectuer des requêtes au moyen d’une interface uti­li­sa­teur graphique. Pour ce faire, ouvrez votre na­vi­ga­teur, et tapez l’adresse suivante :

Après avoir installé les com­po­sants né­ces­saires durant les dif­fé­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 pro­gres­si­ve­ment vous fa­mi­lia­ri­ser avec les dif­fé­rentes options per­met­tant de rédiger vos requêtes.

Pour plus de pré­ci­sions et des ex­pli­ca­tions plus dé­tail­lées sur la mise en place de back-ends et front-ends GraphQL, reportez-vous à l’espace tutoriels sur la page of­fi­cielle du concept API de Facebook.