Comment démarrer avec GraphQL

Développé par Facebook et publié en tant que norme ouverte à tous, GraphQL est conçu comme une alternative aux API REST. Comme REST, GraphQL fournit un moyen de créer et d'utiliser des API basées sur le Web, mais les requêtes et les données renvoyées utilisent des schémas formels et un système de types pour garantir la cohérence.

Dans cet article, nous passerons en revue les bases de la conception et de la mise en œuvre d'une API GraphQL et discuterons de nombreuses considérations et décisions clés que vous prendrez au cours du processus.

Langages et frameworks GraphQL

Si vous envisagez d'utiliser GraphQL comme API pour votre application Web, il y a de fortes chances que le langage et les composants de données que vous utilisez déjà soutiennent vos efforts. Les bibliothèques GraphQL sont disponibles pour presque tous les principaux langages utilisés en production. Les clients sont disponibles pour C#/.NET, Go, Java et Android, JavaScript, Swift/Objective-C et Python, et les bibliothèques serveur couvrent encore plus de domaines.

Si vous débutez entièrement À partir de zéro, il est toujours préférable de choisir le langage, l'environnement d'exécution et la couche de données que vous connaissez le mieux dans d'autres projets. L'utilisation de GraphQL n'impose pas beaucoup de restrictions au serveur ou au client, et il est indépendant de la base de données. Cependant, vous devrez peut-être effectuer une intégration plus ou moins manuelle de votre couche de données en fonction de ce dont il s'agit. (Plus d'informations à ce sujet dans la section suivante.)

Nous utiliserons l'implémentation Python de GraphQL comme référence dans cet article. Les concepts et fonctionnalités seront plus ou moins les mêmes pour les autres langages.

Schéma de requête de données de GraphQL

GraphQL prend en charge les requêtes construites à partir de champs fortement typés dans divers arrangements hiérarchiques. La partie de la création d'une API GraphQL à laquelle vous devez accorder le plus d'attention est le schéma à fournir pour les requêtes.

Dans de nombreux cas, les champs de requête peuvent être mappés un à un à une source de données sous-jacente, afin d'exposer tous les champs pertinents de la base de données (ou d'une autre source de données) pour vos requêtes. Étant donné que les requêtes GraphQL peuvent être considérablement plus ouvertes et variées que leurs homologues REST, vous devez planifier dès le début les champs qui peuvent être interrogés et la manière dont ils seront mappés à votre base de données.

Par exemple, si nous avons une table de base de données pour les films, avec les champs title et year (en tant qu'entier), nous pourrions utiliser une requête GraphQL comme celle-ci :

type Character {
    title: String!
    year: Int
}

Le ! suivant String signifie qu'un champ donné est obligatoire, nous aurions donc besoin d'au moins un titre pour effectuer cette requête.

Vous devez également vous assurer que les champs que vous exposez via GraphQL utilisent des types qui correspondent correctement aux données sous-jacentes. Par exemple, GraphQL ne dispose pas d'un type de données natif « date » ou « datetime », en grande partie à cause de la grande diversité des implémentations disponibles. Si vous souhaitez autoriser les recherches par plages de dates, vous devrez appliquer le formatage des dates tel qu'il est pris en compte via l'API, et également vous assurer que ces demandes de date sont traduites dans leurs équivalents appropriés pour la base de données principale lorsque vous l'interrogez.

Selon le framework que vous utilisez, ce travail a peut-être déjà été effectué pour vous. Graphene, une bibliothèque GraphQL populaire pour Python, fournit des valeurs de date et d'heure au format ISO-8601 en tant que type natif, vous n'avez donc pas à vous en occuper vous-même.

Si votre ensemble de données comporte de nombreux champs, commencez par exposer les plus petit sous-ensemble fonctionnel des champs qui ne nécessitent pas de mise en œuvre de types complexes, par exemple des requêtes simples de type chaîne ou numérique. Vous pouvez ensuite étendre progressivement les champs disponibles au fur et à mesure que vous découvrez comment implémenter des requêtes pour eux via le connecteur GraphQL que vous utilisez.

Stockage et récupération des données GraphQL

Le stockage et la récupération des données depuis votre back-end utilisent généralement le middleware pris en charge par la bibliothèque GraphQL pour votre langage.

Dans de nombreux cas, GraphQL peut effectuer ce travail via des couches de données pour des frameworks d'application courants. La bibliothèque Graphene de Python pour GraphQL, par exemple, prend en charge le framework Web Django, ainsi que l'ORM intégré de Django. Graphene prend également en charge l'ORM SQLAlchemy et ajoute la prise en charge des frameworks populaires Starlette et FastAPI. Il peut également interagir avec les connecteurs de données de Google App Engine et le framework JavaScript Relay (utilisé par React).

Si vous utilisez une couche de données qui n'est décrite par aucun de ces composants, vous pouvez utiliser le middleware et les objets DataLoader de Graphene pour combler l'écart. Ceux-ci vous fournissent des emplacements pour brancher manuellement l'intégration dont vous avez besoin avec votre couche de données. Avec DataLoadervous disposez d'un moyen de regrouper plusieurs demandes simultanées de données associées et de réduire ainsi le nombre d'allers-retours vers votre back-end.

Rien de tout cela ne vous empêche d'effectuer vous-même la mise en cache à n'importe quel niveau de l'application. Par exemple, les réponses que vous renvoyez peuvent être mises en cache via un proxy, tandis que les données du back-end peuvent être mises en cache à l'aide de Memcached ou de Redis. Cela dit, il vous incombe de vous assurer que ces caches sont supprimés chaque fois que les données changent.

Requêtes et mutations GraphQL

GraphQL utilise un format de requête spécifique, appelé « requête de mutation », pour créer, mettre à jour ou supprimer des éléments d'un ensemble de données. Réfléchissez à la manière dont ces requêtes fonctionneront : non seulement aux requêtes que vous autoriserez et aux champs dont vous aurez besoin pour elles, mais également aux données que vous renverrez à partir de la requête après la mutation.

Lorsque vous concevez une requête de mutation, vous pouvez autoriser le renvoi de n'importe quel nombre de champs de sortie. Cela dit, ce n'est probablement pas une bonne idée d'imbriquer des objets de réponse sur plus d'une ou deux couches de profondeur, car cela rend les résultats difficiles à analyser, à la fois lors de l'examen de la requête elle-même et lors de l'écriture de code pour gérer les résultats.

Un autre avertissement important est de ne pas laisser les anciennes habitudes de conception d’API REST dicter la manière dont vous organisez vos requêtes de mutation. Par exemple, plutôt que de créer plusieurs requêtes de mutation pour gérer différents types de modifications sur le même objet (un modèle courant avec REST), vous pouvez les regrouper en une seule requête de mutation. Une façon de procéder consiste à utiliser des champs distincts et non facultatifs pour enregistrer chaque opération possible, comme dans le cas du « vote positif/vote négatif » de cet exemple.

Une autre solution consisterait à utiliser un champ de valeur plus un type d'énumération pour décrire le comportement souhaité avec cette valeur. L'un des grands avantages d'une énumération est qu'elle est sans ambiguïté : vous pouvez l'utiliser pour refléter précisément l'intention, elle est donc hautement auto-documentée. Il y a de fortes chances que la bibliothèque GraphQL de votre langage vous donne un moyen d'utiliser des énumérations qui soit cohérent avec l'implémentation du concept par le langage lui-même. Par exemple, les énumérations GraphQL dans Graphene for Python peuvent ressembler beaucoup à la bibliothèque standard de Python enum classe.

Mise en cache et accélération des performances GraphQL

En réalité, une requête GraphQL interroge et récupère les données de la même manière que n'importe quelle autre requête. Cela signifie qu'elle peut être accélérée par de nombreuses méthodes identiques à celles utilisées pour accélérer les requêtes sur les API :

• Mise en cache: Tout service qui possède une base de données en tant que back-end ou qui renvoie des données depuis un front-end peut bénéficier de la mise en cache aux deux extrémités. Gardez à l'esprit que la responsabilité de l'expiration de ces caches vous incombe, vous devrez donc probablement utiliser les hooks middleware du framework GraphQL (comme ceux décrits ci-dessus pour Graphene) pour déclencher de telles choses. Il est recommandé d'utiliser des identifiants uniques chaque fois que possible pour prendre en charge la mise en cache côté client.
• Curseurs et pagination: Une requête doit avoir une limite supérieure par défaut pour le nombre d'enregistrements qu'elle renvoie à la fois, afin d'éviter que le client et le serveur ne soient submergés. Il est également judicieux de permettre aux clients de décrire explicitement le nombre maximal d'enregistrements à renvoyer et la « page » d'enregistrements à demander. La documentation officielle de GraphQL contient quelques conseils utiles sur la façon d'intégrer les métaphores de pagination dans le format de requête GraphQL.

Outils GraphQL

En plus des bibliothèques disponibles pour différents langages, GraphQL dispose d'une multitude d'outils natifs et tiers pour faciliter le développement de clients, de serveurs, de schémas et de couches de traitement de requêtes :

• Apollo GraphQL consacre ses ressources à la création d'outils open source pour GraphQL, notamment des clients GraphQL et des serveurs GraphQL. Il gère également GraphQL Tools, un ensemble d'utilitaires permettant de générer et de simuler des schémas GraphQL et de « coller » plusieurs API en une seule API, ce qui permet à GraphQL de remplir sa mission de consolidation de plusieurs points de terminaison d'API et de les rendre plus faciles à gérer.
• Si vous envisagez de porter une API existante générée par Swagger vers GraphQL, l'outil Swagger2GraphQL est fait pour cela. Il permet également la maintenance côte à côte d'une API héritée générée par Swagger, ce qui vous permet d'utiliser les deux normes pendant une période de transition.
• Enfin, le groupe GraphQL de Facebook propose quelques outils qui méritent d'être mentionnés. GraphiQL est un IDE intégré au navigateur pour créer des requêtes GraphQL ; il peut être utilisé en interne ou comme solution publique. Il existe également une implémentation JavaScript de GraphQL, une suite de serveurs et de clients GraphQL sur HTTP et un service de langage GraphQL pour les IDE.