GraphQL — qu'est-ce que c'est, langage de requête et application dans les projets mobiles

Qu'est-ce que GraphQL ?

GraphQL — est une spécification et un environnement d'exécution pour les API qui donne au client un contrôle total sur les données qu'il reçoit. Développée par les ingénieurs de Facebook pour résoudre les problèmes de l'application mobile News Feed, la spécification a été publiée comme un standard ouvert en 2015. Depuis 2018, GraphQL est géré par la GraphQL Foundation avec le soutien de la Linux Foundation et d'entreprises comme Apollo, AWS, GitHub, SAP et d'autres.

Contrairement à REST, où chaque endpoint retourne une structure de données fixe, GraphQL utilise un seul endpoint qui accepte une chaîne de requête. Le client décrit dans la requête les champs dont il a besoin, et le serveur retourne exactement ceux-ci. Par exemple, la requête { user(id: "1") { name email } } ne retournera que le nom et l'email de l'utilisateur, sans les champs supplémentaires comme address, phone ou createdAt qui auraient dû être récupérés dans REST.

GraphQL n'est lié à aucune base de données ou langage spécifique. La spécification définit uniquement le format des requêtes et des réponses. Il existe des implémentations serveur sur Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) et d'autres langages. Les bibliothèques client sont disponibles pour toutes les principales plateformes, y compris Apollo Client pour iOS, Android et le web.

Comment fonctionne GraphQL

L'architecture GraphQL se compose de trois composants clés : le schéma (Schema), les résolveurs (Resolvers) et le moteur GraphQL (GraphQL Engine). Le schéma définit les types de données disponibles, les requêtes pouvant être exécutées et les arguments qu'elles acceptent. Les résolveurs sont des fonctions côté serveur qui retournent des données pour chaque champ du schéma. Le moteur reçoit la requête entrante, la valide par rapport au schéma, appelle les résolveurs appropriés et assemble la réponse.

Le processus de traitement d'une requête est le suivant :

• Le client envoie une requête POST à /graphql avec un corps JSON { "query": "..." }
• Le serveur analyse la requête, construit un AST (Arbre Syntaxique Abstrait) et le valide par rapport au schéma
• Le moteur parcourt l'AST, appelant les résolveurs pour chaque champ, collectant les données
• La réponse est retournée au format JSON, correspondant strictement à la structure de la requête

L'avantage clé de l'architecture GraphQL est la résolution au niveau du champ. Dans REST, le développeur obtient tous les champs d'une ressource (peut-être avec des données superflues) ou recourt à des extensions comme ?fields=name,email. Dans GraphQL, ce filtrage est intégré au langage : chaque requête spécifie explicitement les champs nécessaires, et le serveur retourne exactement ceux-ci. Ceci est particulièrement important pour les applications mobiles, où la quantité de données transférées affecte directement la vitesse de chargement et la consommation de données.

Query, Mutation et Subscription

GraphQL définit trois types d'opérations, chacun correspondant à un scénario d'interaction spécifique. Query — pour la lecture de données, analogue à GET dans REST. Mutation — pour la modification de données (création, mise à jour, suppression), analogue à POST/PUT/DELETE. Subscription — pour les mises à jour en temps réel via WebSocket, qui n'a pas d'analogue direct dans le REST classique (nécessite des solutions supplémentaires comme WebSocket ou Server-Sent Events).

La syntaxe de base des requêtes est intuitive :

// Requête simple avec argument
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation retournant des données modifiées
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — écoute les mises à jour en temps réel
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query s'exécute en parallèle — tous les champs au même niveau sont chargés simultanément. Cela permet de charger des données connexes (utilisateur et ses publications) en une seule requête sans plusieurs allers-retours. Mutation s'exécute séquentiellement — les mutations dans une requête sont exécutées les unes après les autres dans l'ordre de déclaration. Subscription établit une connexion persistante via WebSocket, par laquelle le serveur envoie des données lorsqu'un événement se produit.

Les opérations peuvent accepter des variables pour séparer les données de la requête, des directives (@include, @skip) pour l'inclusion conditionnelle de champs et des fragments pour réutiliser des ensembles de champs. Ces capacités rendent les requêtes GraphQL flexibles et réutilisables, ce qui est particulièrement important dans les grands projets avec de nombreux écrans et composants.

Schéma et système de types de GraphQL

Au cœur de GraphQL se trouve un système de types décrivant toutes les données et opérations API possibles. Le schéma est une description des types que le serveur peut retourner et des requêtes qu'il accepte. Le schéma est écrit en Schema Definition Language (SDL) et sert de contrat entre le client et le serveur. Le client peut obtenir le schéma par introspection — une requête spéciale __schema qui retourne une description complète de l'API.

Exemple de schéma pour un blog :

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Le point d'exclamation (!) indique un champ non nul — il sera garantieument présent dans la réponse. Les crochets [ ] désignent une liste. GraphQL prend en charge les types scalaires (Int, Float, String, Boolean, ID), les types objet, enum, union, interface et les types d'entrée (pour les arguments de mutation). Le typage strict auto-documente l'API et permet aux outils client de générer du code : types TypeScript, classes de données Kotlin, structures Swift.

L'introspection est une fonctionnalité unique de GraphQL absente dans REST. Le client peut envoyer une requête au schéma et obtenir une description complète de tous les types, champs, arguments et directives. C'est la base d'outils comme GraphiQL et Apollo Studio, qui génèrent automatiquement de la documentation et de l'autocomplétion pour les développeurs. L'introspection permet également d'écrire des tests automatisés vérifiant la conformité du schéma avec la structure attendue.

Comparaison de GraphQL avec REST

Le choix entre GraphQL et REST est l'une des décisions architecturales clés lors de la conception d'une API. Les deux approches ont leurs forces et leurs faiblesses, et le choix dépend des exigences spécifiques du projet. REST l'emporte en simplicité et universalité, GraphQL en flexibilité et efficacité des requêtes. Regardons le tableau comparatif.

Le principal inconvénient de GraphQL est la complexité du cache. Dans REST, le cache HTTP fonctionne au niveau de l'URL : une requête à /api/users/42 retourne toujours la même structure, et la réponse peut être mise en cache par URL. Dans GraphQL, toutes les requêtes vont à un seul endpoint, et la structure de la réponse dépend du corps de la requête. Pour résoudre ce problème, Apollo Client utilise un cache normalisé côté client, qui décompose les réponses en entités individuelles par id et les met automatiquement à jour à la réception de nouvelles données.

Un autre aspect important est le problème N+1. Lors de la demande de données imbriquées (par exemple, les publications d'un utilisateur et les commentaires pour chaque publication), GraphQL peut exécuter une requête SQL séparée pour chaque élément de la liste. Il est résolu à l'aide de DataLoader — un utilitaire pour regrouper et mettre en cache les requêtes de base de données, qui regroupe les requêtes individuelles en un seul lot. Dans REST, ce problème est moins prononcé car le développeur contrôle la structure de la réponse côté serveur.

Exemples de requêtes GraphQL

Regardons des exemples pratiques d'utilisation de GraphQL dans une application mobile Kotlin avec Apollo Client. Les exemples montrent des scénarios typiques : chargement de données pour un écran de profil (query), création d'une nouvelle publication (mutation) et abonnement aux nouveaux commentaires (subscription). Chaque exemple comprend à la fois la requête GraphQL et le code côté client.

Query : Chargement d'un profil avec publications

Une seule requête GraphQL charge l'utilisateur, ses dernières publications et le nombre total d'abonnés. Dans REST, cela nécessiterait au moins 2-3 requêtes : /users/42, /users/42/posts, /users/42/stats. GraphQL les combine en un seul aller-retour, réduisant le temps de chargement de l'écran sur les connexions lentes.

// Requête GraphQL (dans le fichier .graphql)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Appel côté client (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation : Création d'une nouvelle publication

La mutation non seulement crée une ressource, mais retourne également ses données actuelles pour mettre à jour l'interface utilisateur. Le champ __typename est utilisé par Apollo Client pour la normalisation du cache — le client mettra automatiquement à jour l'enregistrement Post dans le cache lors d'une réponse de mutation réussie.

// Mutation GraphQL
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Appel de mutation avec type input
val input = CreatePostInput(
    title = "Nouvelle publication sur GraphQL",
    content = "GraphQL simplifie le travail avec les API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Un avantage important de GraphQL par rapport à REST dans le contexte du développement mobile est la génération automatique de code. Apollo Client pour Kotlin (Apollo GraphQL) génère des classes typées sûres à partir de fichiers .graphql au moment de la construction. Si le serveur modifie le schéma, le projet ne sera pas construit tant que les requêtes ne seront pas mises à jour. Cela évite les erreurs d'exécution typiques de REST, où les modifications de la structure de la réponse peuvent passer inaperçues lors du développement.

Écosystème : Apollo, Relay et outils

L'écosystème GraphQL comprend plusieurs bibliothèques et outils clés qui simplifient le développement et l'exploitation. Apollo Client est la bibliothèque client la plus populaire, prenant en charge React, iOS, Android et Kotlin Multiplatform. Relay de Facebook est une alternative pour les applications React avec une approche unique de la gestion des données et du cache. Le choix entre Apollo et Relay dépend de la plateforme et des exigences de performance.

Côté serveur, les leaders sont Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) et graphql-ruby. Pour le développement de schémas et les tests de requêtes, GraphiQL est utilisé — un IDE interactif intégré au navigateur. Apollo Studio fournit des métriques de performance, le traçage des requêtes et la gestion des schémas pour les environnements de production. Mention séparée mérite GraphQL Code Generator — un outil qui génère des types TypeScript, Kotlin, Swift et Dart à partir d'un schéma SDL.

Pour le développement mobile, Apollo Kotlin (Apollo GraphQL) présente un intérêt particulier — une bibliothèque entièrement écrite en Kotlin avec prise en charge des coroutines, Flow et Multiplatform. Elle permet d'utiliser des requêtes GraphQL unifiées pour Android et iOS dans les projets Kotlin Multiplatform. Apollo Kotlin normalise le cache, prend en charge les erreurs au niveau du champ (erreurs partielles) et génère automatiquement des modèles de données à partir de fichiers .graphql. Cela fait de GraphQL le choix préféré pour les grands projets mobiles où la vitesse de développement et la sécurité des types sont importantes.