🚀 GraphQL – Le Guide Ultime

GraphQL est un langage de requête (Query Language) pour vos APIs, et un runtime côté serveur pour exécuter ces requêtes. Il a été créé par Facebook en 2012 (rendu public en 2015) pour résoudre les problèmes de leurs applications mobiles.

L'idée centrale est de donner le pouvoir au client (l'app mobile, le site web) de demander *exactement* les données dont il a besoin, ni plus, ni moins.

Le Problème avec les APIs "REST" Classiques

Imaginons un blog. Pour afficher la page d'un article, une app mobile (le "client") a besoin :
1. Des infos sur l'article (titre, contenu).
2. Des infos sur l'auteur (nom, avatar).
3. La liste des commentaires.

Avec une API REST classique, le client doit faire 3 appels réseau (voire plus) :

GET /api/articles/123         --> (Renvoie le titre, contenu, et "auteur_id")
GET /api/users/456            --> (On utilise "auteur_id" pour chercher l'auteur)
GET /api/articles/123/comments --> (On cherche les commentaires)

Le problème du "Over-fetching" et "Under-fetching"

La Solution GraphQL : 1 Requête, 1 Réponse

Avec GraphQL, le client fait 1 seul appel (un POST sur /graphql) avec une "requête" qui décrit *exactement* la forme des données voulues :

# Le client envoie CETTE requête (qui ressemble à du JSON)
query {
  article(id: "123") {
    titre
    contenu
    auteur {
      nom
      avatar
    }
    commentaires {
      texte
    }
  }
}

Le serveur GraphQL (intelligent) comprend cette requête, va chercher les données (en 1 ou 3 fois, c'est son problème) et renvoie un JSON unique qui *correspond parfaitement* à la forme de la requête.

Qui utilise GraphQL ? (Exemples de Projets)

• Netflix : L'utilise pour son API de "gateway" qui unifie des centaines de microservices backend pour servir les apps TV, web, et mobiles.
• GitHub : Leur API publique (v4) est 100% GraphQL. Elle a remplacé leur API REST (v3).
• Shopify : Utilise GraphQL massivement pour les APIs de sa plateforme e-commerce, permettant aux développeurs de plugins de ne récupérer que les infos produits/clients nécessaires.
• Airbnb, Twitter, PayPal... : De nombreuses entreprises l'utilisent pour unifier leurs sources de données.

GraphQL n'est pas "mieux" que REST dans l'absolu, mais il répond à des problèmes différents, notamment pour les applications complexes et les clients multiples (web, mobile, montre connectée).

Tableau Comparatif Fondamental

Exemple de Scénario : Le "Dashboard"

Un dashboard doit afficher : l'utilisateur courant, ses 5 derniers articles, et ses 3 derniers commentaires.

// Appel 1
GET /api/me

// Appel 2
GET /api/me/articles?limit=5

// Appel 3
GET /api/me/comments?limit=3

// Appel 1 (POST /graphql)
query {
  me {
    nom
    email
    derniersArticles(limit: 5) {
      titre
      datePublication
    }
    derniersCommentaires(limit: 3) {
      texte
      article { titre }
    }
  }
}

Le Schéma est le cœur absolu de GraphQL. C'est le contrat formel entre le client et le serveur. Il définit 100% de ce qu'un client *peut* demander.

Il est écrit en SDL (Schema Definition Language). C'est un langage simple et lisible.

Types d'Entrée : Query, Mutation, Subscription

Un schéma expose 3 "types" principaux qui définissent les points d'entrée de l'API :

• type Query { ... } : Définit toutes les opérations de Lecture possibles (ex: user(id: ID!): User, allPosts: [Post]).
• type Mutation { ... } : Définit toutes les opérations d'Écriture possibles (ex: createPost(title: String!): Post).
• type Subscription { ... } : Définit toutes les opérations Temps-Réel possibles (ex: newCommentOnPost(postId: ID!): Comment).

Exemple de Schéma (schema.graphql) - Version Enrichie

# 1. Définition d'un type "scalaire" personnalisé (le format de base)
scalar Date

# 2. Définition d'un "Enum" (choix limité)
enum Role {
  USER
  ADMIN
}

# 3. Définition d'une "Interface" (Polymorphisme)
#    Un contrat que d'autres types doivent implémenter.
interface Node {
  id: ID!
  createdAt: Date!
}

# 4. Définition d'un type Objet "User" (implémente Node)
type User implements Node {
  id: ID! # ! = Non-Null
  createdAt: Date!
  username: String!
  email: String!
  role: Role!
  posts: [Post] # Un utilisateur peut avoir une LISTE de Posts
}

# 5. Définition d'un type Objet "Post" (implémente Node)
type Post implements Node {
  id: ID!
  createdAt: Date!
  title: String!
  content: String
  author: User! # Un Post a UN Auteur (lien vers le type User)
  comments: [Comment] # Un Post a une LISTE de Comments
}

# 6. Définition d'une "Union" (Polymorphisme)
#    Un "SearchResult" peut être SOIT un User, SOIT un Post.
union SearchResult = User | Post

# 7. Point d'entrée pour la LECTURE
type Query {
  user(id: ID!): User
  post(id: ID!): Post
  allPosts: [Post!]!
  # Exemple d'union
  search(term: String!): [SearchResult]
}

# 8. Point d'entrée pour l'ECRITURE
type Mutation {
  createPost(title: String!, content: String): Post
  addComment(postId: ID!, text: String!): Comment
}

Une Query est l'opération de base pour lire des données. Le client "dessine" la forme du JSON qu'il souhaite recevoir, en respectant le Schéma.

Exemple 1 : Requête Imbriquée (Le "Graph")

Je veux le titre du post "123", mais aussi le username de son auteur et le text de tous ses commentaires.

# REQUÊTE CLIENT
query {
  post(id: "123") {
    title
    author {
      username
    }
    comments {
      text
    }
  }
}

# RÉPONSE SERVEUR (JSON)
{
  "data": {
    "post": {
      "title": "Mon Premier Article",
      "author": { "username": "JeanDupont" },
      "comments": [
        { "text": "Super article !" },
        { "text": "Je ne suis pas d'accord." }
      ]
    }
  }
}

Exemple 2 : Directives (@include / @skip)

Les directives sont de la logique conditionnelle *côté client*. Elles permettent d'altérer la structure de la requête sans changer le string.

# REQUÊTE CLIENT (avec variable $withComments = false)
query GetPost($postId: ID!, $withComments: Boolean!) {
  post(id: $postId) {
    title
    # Le champ 'comments' ne sera inclus que si $withComments est true
    comments @include(if: $withComments) {
      text
    }
    # Le champ 'author' sera sauté si $withComments est true
    author @skip(if: $withComments) {
      username
    }
  }
}

# RÉPONSE SERVEUR (si $withComments = false)
{
  "data": {
    "post": {
      "title": "Mon Premier Article",
      "author": { "username": "JeanDupont" }
      # Le champ 'comments' n'est pas présent !
    }
  }
}

Exemple 3 : Introspection (__typename) et Unions

Quand une requête renvoie une Union (ex: SearchResult), comment savoir si c'est un User ou un Post ? On utilise __typename et des fragments "inline" (... on Type).

# REQUÊTE CLIENT
query {
  search(term: "GraphQL") {
    __typename # Champ magique : renvoie le nom du type
    
    ... on User {
      # Champs à prendre SI c'est un User
      username
    }
    ... on Post {
      # Champs à prendre SI c'est un Post
      title
      author { username }
    }
  }
}

# RÉPONSE SERVEUR
{
  "data": {
    "search": [
      { "__typename": "Post", "title": "GraphQL est super" , "author": { "username": "Jean" } },
      { "__typename": "User", "username": "GraphQLFan" }
    ]
  }
}

Une Mutation est l'opération pour modifier les données. La convention est que la mutation renvoie l'objet qui vient d'être modifié. Cela permet au client de récupérer la nouvelle donnée (ex: l'ID généré) en un seul aller-retour.

Exemple 1 : Création (CREATE)

Je veux créer un nouveau post. Je demande au serveur de me renvoyer l'id (généré) et le title du post créé.

# REQUÊTE CLIENT (POST sur /graphql)
mutation {
  createPost(title: "Nouveau Post", content: "Contenu...") {
    id
    title
  }
}

# RÉPONSE SERVEUR (JSON)
{
  "data": {
    "createPost": {
      "id": "789", # ID généré par le serveur
      "title": "Nouveau Post"
    }
  }
}

Exemple 2 : Mise à jour (UPDATE) avec un type input

Pour les mises à jour, on utilise des types input pour regrouper les arguments (voir 8.1).

Ajout au Schéma (schema.graphql) :

# Un "input" est comme un "type", mais pour les arguments
input UpdatePostInput {
  title: String
  content: String
}

# Ajout à "type Mutation"
type Mutation {
  ...
  updatePost(id: ID!, input: UpdatePostInput!): Post
}

Requête de mise à jour (notez l'utilisation de variables) :

# REQUÊTE CLIENT
mutation UpdatePost($postId: ID!, $changes: UpdatePostInput!) {
  updatePost(id: $postId, input: $changes) {
    id
    title
    content
  }
}

# VARIABLES JSON
{
  "postId": "789",
  "changes": {
    "title": "Titre mis à jour"
  }
}

Exemple 3 : Suppression (DELETE)

Une mutation de suppression renvoie souvent l'ID de l'objet supprimé ou un booléen de succès.

Ajout au Schéma (schema.graphql) :

type Mutation {
  ...
  deletePost(id: ID!): ID # Renvoie l'ID du post supprimé
}

Requête de suppression :

mutation {
  deletePost(id: "789")
}

# RÉPONSE SERVEUR
{ "data": { "deletePost": "789" } }

Les Queries et Mutations sont des opérations "demande/réponse" classiques (pull). Le client demande, le serveur répond. Mais que faire si le client veut être notifié par le serveur ? (ex: un chat en direct, une notification "nouveau commentaire").

C'est le rôle des Subscriptions. Elles maintiennent une connexion longue durée (généralement via WebSockets) entre le client et le serveur.

Le Flux de Fonctionnement (Ex: avec Apollo PubSub)

1. Le Client (ex: app React) envoie une requête subscription au serveur GraphQL (ex: Apollo Server).
2. Le Serveur établit une connexion WebSocket.
3. Le Client A "écoute" (s'abonne) à un "canal" (topic). (ex: newComment(postId: "123")).
4. Le Client B exécute une mutation (ex: addComment(postId: "123", ...)).
5. Le **Résolveur** de la mutation addComment fait 2 choses :
   a. Il sauvegarde le commentaire en BDD.
   b. Il "publie" le nouveau commentaire sur un canal PubSub (ex: pubsub.publish('COMMENT_ADDED', { newComment: leNouveauCommentaire })).
6. Le Serveur (qui écoutait ce canal) envoie le "push" (leNouveauCommentaire) au Client A via le WebSocket.

Exemple de Code (Client & Schéma)

Schéma (schema.graphql) :

type Subscription {
  # Être notifié (via WebSocket) d'un nouveau commentaire sur un post
  newComment(postId: ID!): Comment
}

Requête Client (ex: avec Apollo Client) :

# Le client "s'abonne" à cet événement
subscription OnNewComment($postId: ID!) {
  newComment(postId: $postId) {
    # Quand un nouveau commentaire arrive, je veux ces champs
    id
    text
    author {
      username
    }
  }
}

Chaque fois qu'un commentaire est ajouté (via une mutation), le serveur poussera la donnée (id, text, author) au client, qui pourra mettre à jour l'interface graphique sans que l'utilisateur n'ait à rafraîchir la page.

Le Schéma est le "Quoi" (le contrat). Les Résolveurs sont le "Comment" (l'implémentation). Un résolveur est une fonction côté backend (JS, Java, Python) qui est "mappée" (liée) à un champ du Schéma.

Les 4 Arguments d'un Résolveur

Chaque fonction de résolveur reçoit 4 arguments : (parent, args, context, info).

Exemple (avec context pour l'auth)

// Simule la création du serveur
const server = new ApolloServer({
  typeDefs, // Le schéma
  resolvers,
  context: async ({ req }) => {
    // Fonction qui crée le 'context' pour chaque requête
    // 1. Lire le token "Authorization: Bearer ..."
    const token = req.headers.authorization || '';
    // 2. Trouver l'utilisateur
    const currentUser = await getUserFromToken(token);
    // 3. Le retourner. Il sera dispo dans tous les résolveurs.
    return { currentUser, db };
  }
});

// Dans vos résolveurs...
const resolvers = {
  Query: {
    me: (parent, args, context) => {
      // 4. Utiliser le context !
      if (!context.currentUser) {
        throw new Error("Authentification requise !");
      }
      return context.currentUser;
    }
  },
  Mutation: {
    createPost: (parent, args, context) => {
      // 5. Utiliser le context pour l'authentification
      if (!context.currentUser) throw new Error("Non autorisé");
      
      // 6. Utiliser le context pour la BDD
      return context.db.posts.create({ ...args, authorId: context.currentUser.id });
    }
  }
};

Le "N+1 Query Problem" (Problème de Performance)

C'est le *principal* problème de performance de GraphQL (côté serveur).
Scénario : Le client demande 10 posts, et pour chaque post, l'auteur.
1. Le résolveur Query.allPosts s'exécute. (1 appel BDD : SELECT * FROM posts LIMIT 10).
2. Le serveur a 10 objets Post. Pour chacun, il doit résoudre Post.author.
3. Il exécute le résolveur Post.author... 10 fois. (10 appels BDD : SELECT * FROM users WHERE id = ...).
Total : 1 + 10 = 11 appels BDD. C'est un désastre.

Solution : DataLoader (de Facebook). C'est un outil qui "batch" (regroupe) et "cache" les requêtes. Il intercepte les 10 demandes d'auteurs, les fusionne en une seule (SELECT * FROM users WHERE id IN (1, 2, 3...)) et redistribue les résultats.

Le système de types de GraphQL est le fondement de son Schéma. Il existe plusieurs catégories de types.

1. Types Scalaires (Types de base)

Ce sont les "feuilles" de l'arbre. Les données brutes. Il y en a 5 par défaut :

2. Types Objets (type)

Ce sont les "nœuds" de l'arbre. Des types que vous définissez, qui ont leurs propres champs.

type User {
  id: ID!
  username: String
  age: Int
}

3. Types d'Entrée (input)

Un input a la même syntaxe qu'un type, mais il est utilisé *exclusivement* comme argument pour les Mutations. Il regroupe les champs.

# Au lieu de :
#   mutation createUser(username: String!, email: String!, age: Int)
# On fait :
input CreateUserInput {
  username: String!
  email: String!
  age: Int
}
mutation {
  createUser(input: CreateUserInput!): User
}

4. Modificateurs de Type (! et [])

Ce sont les plus importants. Ils "enveloppent" les autres types pour changer leur comportement.

Problème : GraphQL est génial pour un monolithe. Mais en 2025, on utilise des microservices.
L'équipe A gère le service "Users" (avec son schéma GraphQL).
L'équipe B gère le service "Products" (avec son schéma GraphQL).
L'équipe C gère le service "Reviews" (avec son schéma GraphQL).

Comment le client (l'app mobile) peut-il faire une seule requête qui mélange les trois ? Doit-il connaître 3 endpoints GraphQL ?

Solution : Apollo Federation (Fédération).

Le Concept du "Supergraph"

La Fédération est une architecture qui consiste à :

1. Avoir plusieurs serveurs GraphQL indépendants (des "subgraphs"), ex: users, products.
2. Chaque "subgraph" étend les types des autres.
3. Avoir une Gateway (Passerelle) unique, qui est le seul point d'entrée pour le client.
4. La Gateway télécharge les schémas de tous les "subgraphs" et les compile en un "Supergraph" unifié.
5. Quand une requête client arrive, la Gateway la décompose, l'envoie aux bons "subgraphs" en parallèle, et ré-assemble la réponse.

Exemple de "Federation" (Code)

C'est le concept le plus puissant de l'écosystème GraphQL moderne.

# Schéma du service "Users"
type User @key(fields: "id") {
  id: ID!
  username: String
}

type Query {
  user(id: ID!): User
}

# Schéma du service "Products"
# Il "étend" le type User !
type User @key(fields: "id") @extends {
  id: ID! @external
  # Il ajoute un nouveau champ à User
  purchasedProducts: [Product]
}

type Product {
  id: ID!
  name: String
}

Résultat pour le Client (via la Gateway) :
Le client ne voit qu'un seul schéma (le Supergraph) et peut faire une requête qui mélange les deux, sans savoir qu'ils sont séparés :

query {
  user(id: "1") {
    username          # -> Résolu par le service Users
    purchasedProducts { # -> Résolu par le service Products
      name
    }
  }
}

1. Variables de Requête

Jusqu'à présent, nous avons "hardcodé" les IDs (ex: post(id: "123")). C'est très mauvais :
1. Sécurité : C'est une porte ouverte à l'injection si on construit le string de requête à la main.
2. Réutilisabilité : On ne peut pas réutiliser la même requête pour l'ID "456".

La solution est d'utiliser des variables. La requête GraphQL (POST) est envoyée en 2 parties : le "query string" et un objet JSON "variables".

Exemple de Requête avec Variable

# 1. Le "Query String" (Le "template")
#    - On "nomme" la query (ex: GetPostById)
#    - On déclare la variable ($postId) et son type (ID!)
query GetPostById($postId: ID!) {
  # On utilise la variable ($postId)
  post(id: $postId) {
    id
    title
  }
}

# 2. L'objet "Variables" (Le "contenu", envoyé en JSON séparé)
{
  "postId": "123"
}

Le serveur GraphQL reçoit les deux, vérifie que $postId est bien un ID!, et "injecte" la variable dans la requête avant de l'exécuter. C'est 100% sécurisé et réutilisable.

2. Fragments

Les Fragments sont des "morceaux de requête" réutilisables.
Problème : J'ai deux requêtes (newestPost et featuredPost) et pour les deux, je veux les *mêmes* champs (id, titre, auteur). Je me répète (DRY).

Exemple de Requête avec Fragment

# 1. Définir le Fragment
#    C'est un "morceau" de champs sur le type "Post"
fragment PostFields on Post {
  id
  title
  author {
    username
  }
}

# 2. Utiliser le Fragment
query {
  newestPost {
    ...PostFields # "étale" tous les champs du fragment ici
    date
  }
  
  featuredPost {
    ...PostFields # "étale" les mêmes champs ici
    views
  }
}

# 3. La requête finale (ce que le serveur "voit")
# query {
#   newestPost {
#     id
#     title
#     author { username }
#     date
#   }
#   featuredPost {
#     id
#     title
#     author { username }
#     views
#   }
# }

GraphQL n'est qu'une spécification (un "standard"). On ne "télécharge" pas GraphQL. On télécharge des outils (librairies) qui *implémentent* cette spécification. L'écosystème est dominé par Apollo.

GraphiQL : L'IDE indispensable

GraphiQL (notez le 'i') est un IDE (un outil de développement) qui tourne dans votre navigateur. La plupart des serveurs GraphQL (comme Apollo Server) l'activent automatiquement en mode "développement".

C'est l'outil n°1 pour tester et débugger une API GraphQL.
Il offre :

• Éditeur de Requête (Gauche) : Avec auto-complétion *totale* (il lit le Schéma !).
• Panneau de Variables (Bas Gauche) : Pour tester vos variables JSON.
• Fenêtre de Résultat (Droite) : Affiche la réponse JSON (ou l'erreur).
• "Docs" (Extrême Droite) : L'introspection.
  C'est la fonction la plus puissante. Le GraphiQL "interroge" l'API sur son propre Schéma (une "introspection query"). Il génère une documentation *interactive* et *toujours à jour* de 100% de l'API (tous les types, queries, mutations, et leurs arguments). C'est la fin de la "documentation d'API obsolète".

Références Extérieures (Liens)