Utilisation de GraphQL

Introduction

GraphQL, initialement développé par Facebook avant d’être transféré à une fondation open source, est un langage de requête et un environnement d’exécution côté serveur pour les API qui révolutionne la manière d’interroger et de mettre à jour des données stockées dans divers systèmes. Son intégration dans une application Spring Boot, en tant que couche intermédiaire, permet une gestion flexible et efficace des requêtes et des mises à jour de données. Offrant une alternative aux architectures REST, GraphQL se distingue par son typage statique, permettant des requêtes précises et des réponses conformes aux attentes, ainsi que la capacité d’agréger des données de sources multiples en une seule requête. Ce langage simplifie également l’évolution de l’API en facilitant l’ajout ou la suppression de champs sans impacter les clients existants, réduisant ainsi la complexité liée à la gestion des versions de l’API.

Schémas GraphQL

Un schéma GraphQL définit les types d’objets qui peuvent être retournés par une API et les champs qui peuvent être interrogés. Ce schéma est constitué de définitions de types. Lorsqu’une requête est envoyée au serveur GraphQL, elle est validée par rapport à ce schéma avant d’être exécutée pour produire les résultats.

Examinons certains des types qui composent un schéma GraphQL.

1. Types d’objets et champs

Les types d’objets dans GraphQL décrivent les objets que nous pouvons récupérer via notre API, ainsi que leurs champs spécifiques. Par exemple, un objet Mission pourrait être défini de la manière suivante :

Schéma de Mission :

type Mission { 
  id: ID! 
  titre: String 
  astronaute: Astronaute 
}

Dans ce schéma, Mission est un type d’objet avec trois champs : id (un identifiant unique pour chaque mission, marqué comme obligatoire avec !), titre (une chaîne représentant le titre de la mission), et astronaute (qui représente un objet de type Astronaute associé à la mission).

2. Arguments

Dans GraphQL, chaque champ d’un type d’objet peut inclure un nombre variable d’arguments. Ces arguments sont...

Queries et mutations

GraphQL utilise un langage de requête spécifique, souvent désigné comme un langage spécifique au domaine (DSL). Du point de vue du client, il existe principalement deux types d’opérations dans ce langage :

La requête (query), qui est utilisée pour récupérer des données.
La mutation, employée pour modifier ou insérer des données.

1. Requête (query)

Les opérations dans GraphQL sont semblables aux opérations CRUD. Une requête (query) est utilisée pour lire les données, à l’instar de GET dans REST, tandis qu’une mutation permet de créer, mettre à jour ou supprimer des données, comme le feraient PUT, DELETE ou POST dans REST.

Une requête GraphQL ressemble visuellement à du JSON, mais n’en est pas. C’est une demande simple pour récupérer des champs spécifiques sur un objet. Par exemple, une requête simple pour obtenir des informations sur des missions et leurs astronautes pourrait ressembler à ceci :

query MissionsAndAstronautes { 
  allMissions { 
    id 
    titre 
    astronaute { 
      nom 
    } 
  } ...

Utilisation de Spring Boot

Nous allons créer une application API Mission simple en utilisant GraphQL et Spring Boot en ajoutant la dépendance spring-boot-starter-graphql dans notre fichier pom.xml. Grâce à ce starter, nous pouvons rapidement mettre en place un serveur GraphQL. Nous incluons également la dépendance spring-boot-starter-web pour exposer les API GraphQL via le point de terminaison /graphql. Cela permet d’accéder facilement aux fonctionnalités GraphQL via un serveur web standard.

1. Création du schéma

Les fichiers de schéma dans GraphQL peuvent avoir les extensions .graphqls ou .gqls. Par défaut, le starter GraphQL recherche les fichiers de schéma dans le répertoire src/main/resources/graphql. Nous pouvons personnaliser l’emplacement du schéma en ajoutant spring.graphql.schema.locations dans le fichier application.properties.

Exemple de configuration dans application.properties :

spring.graphql.schema.locations=/graphql-schema

Dans notre application Mission, nous aurons deux types d’objets : Mission et Astronaute. Nous disposerons de deux requêtes : une pour obtenir toutes les missions et une autre pour obtenir une mission par son identifiant. Nous inclurons également une mutation pour mettre à jour une mission.

Voici à quoi ressemblera notre fichier schema.graphqls :

# Definition de Type 
type...

Query, mutation et mapping

GraphQL utilise plusieurs annotations pour faciliter ces mappages.

1. @SchemaMapping

Cette annotation est utilisée pour associer une méthode de gestion à une paire type-champ. Elle prend deux paramètres : typeNom et value. Le typeNom indique s’il s’agit d’une opération de type Query ou Mutation. Cette spécification peut se faire au niveau de la classe ou de la méthode. La value correspond au nom du champ tel qu’il est défini dans le schéma GraphQL. Si non spécifié, le nom de la méthode est utilisé par défaut.

Par exemple, pour mapper la requête allMissions, nous pourrions la définir ainsi :

@SchemaMapping(typeNom = "Query", value="allMissions") 
public List<Mission> getAllMissions() { 
  return missionRepository.allMissions(); 
}

2. @QueryMapping

L’annotation @QueryMapping est une annotation composite indiquant que typeNom est une Query.

Par exemple, pour définir le gestionnaire de la requête missionById, qui prend un argument id, nous pouvons utiliser l’annotation @Argument pour lier un argument nommé de GraphQL à un paramètre de méthode :

@QueryMapping 
public Mission missionById(@Argument Integer id) { 
  return missionRepository.missionById(id); 
}...

Tests de l’API

Nous pouvons lancer l’application Spring Boot pour accéder aux API GraphQL, qui seront disponibles par défaut sur localhost:8080/graphql. Pour tester les API, un outil tel que Postman sera nécessaire.

Pour tester la requête allMissions, nous pouvons envoyer un payload spécifique dans une requête POST, par exemple :

{ 
  allMissions { 
    id 
    titre 
    astronaute { 
      nom 
    } 
  } 
}

Cette requête Postman nous permet d’obtenir les informations de toutes les missions, y compris les détails des astronautes.

De même, pour tester la requête missionById, nous pouvons utiliser un payload qui cible une mission spécifique par son identifiant :

{ 
  missionById(id: 10) { 
    id 
    titre 
    astronaute { 
      nom 
    } 
  } 
}

Pour tester notre mutation updateMission, le payload serait structuré comme suit :

mutation { 
  updateMission(id: 2, titre: "Java World v3") { 
    id 
    titre ...

Utilisation de GraphiQL

GraphiQL est un environnement de développement intégré (IDE) interactif et graphique pour GraphQL, accessible directement depuis un navigateur. Cet outil est particulièrement utile pour l’apprentissage et la mise à l’essai des requêtes GraphQL. Il offre des fonctionnalités telles que la mise en évidence de la syntaxe, l’autocomplétion, la documentation automatique et bien d’autres avantages.

Par défaut, GraphiQL n’est pas activé dans les projets Spring Boot utilisant GraphQL. Pour l’activer, il suffit d’ajouter la propriété suivante dans le fichier de configuration :

Fichier properties de l’application :

spring.graphql.graphiql.enabled=true

Après avoir activé GraphiQL et redémarré l’application Spring Boot, il est possible d’accéder à l’interface GraphiQL en naviguant sur http://localhost:8080/graphiql dans un navigateur web. Cette action ouvrira la fenêtre GraphiQL, offrant ainsi un environnement interactif pour tester et explorer les requêtes GraphQL.

Points clés

Points à retenir :

GraphQL est un langage de requête pour API et un moteur côté serveur.
Un schéma GraphQL définit les types d’objets qui peuvent être retournés par une API et les champs qui peuvent être interrogés.
GraphiQL est un environnement de développement intégré (IDE) interactif et graphique pour GraphQL.