GraphQL en 2025 : guide complet et cas d'usage

GraphQL est un langage de requête pour APIs développé par Facebook en 2015, devenu un standard pour de nombreuses applications modernes. Contrairement aux APIs graphql REST traditionnelles, il permet aux clients de demander exactement les données dont ils ont besoin, ni plus ni moins.

REST vs GraphQL : les différences fondamentales

Avec REST, vous avez un endpoint par ressource. Pour récupérer un utilisateur avec ses commandes et leurs produits, vous faites 3 requêtes. Avec graphql, une seule requête suffit :

query {
  user(id: "42") {
    name
    email
    orders {
      total
      products {
        name
        price
      }
    }
  }
}

Le over-fetching (trop de données) et l'under-fetching (pas assez) disparaissent. Le client contrôle exactement ce qu'il reçoit.

Le schéma GraphQL : contrat API

Le schéma définit les types, les requêtes possibles et les mutations disponibles. C'est le contrat entre le serveur et les clients :

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(page: Int, limit: Int): [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
}

Le point d'exclamation ! signifie non-nullable. Le schéma est auto-documenté et peut générer des interfaces TypeScript automatiquement.

Apollo Server avec Node.js

const { ApolloServer } = require('@apollo/server');
const { startStandaloneServer } = require('@apollo/server/standalone');

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });

Les resolvers sont des fonctions qui récupèrent les données pour chaque champ du schéma. Ils peuvent appeler une BDD, une API REST, un cache Redis, etc.

Subscriptions : données en temps réel

graphql supporte les subscriptions pour les mises à jour en temps réel via WebSockets :

subscription {
  orderStatusChanged(userId: "42") {
    id
    status
    updatedAt
  }
}

N+1 Problem et DataLoader

Le problème N+1 est courant en graphql : pour 10 utilisateurs, le resolver orders s'exécute 10 fois, générant 10 requêtes SQL. DataLoader de Facebook résout ce problème en regroupant les requêtes en une seule :

const ordersLoader = new DataLoader(async (userIds) => {
  const orders = await Order.findAll({ where: { userId: userIds } });
  return userIds.map(id => orders.filter(o => o.userId === id));
});

Authentification et autorisation

GraphQL n'impose pas de mécanisme d'authentification. JWT dans le header Authorization est le choix standard. L'autorisation se gère au niveau des resolvers ou via des directives custom comme @auth.

Pour approfondir, la documentation Apollo GraphQL couvre tous les cas d'usage avancés.

Quand choisir GraphQL ?

GraphQL excelle pour les applications avec des clients multiples (web, mobile, tiers) ayant des besoins différents, les schémas de données complexes et les équipes frontend autonomes. Pour une API simple avec peu d'endpoints et des clients homogènes, REST reste souvent plus simple.

Conclusion

GraphQL résout élégamment les problèmes de sur-récupération et de sous-récupération des APIs REST. Son typage fort, son schéma auto-documenté et sa flexibilité en font un excellent choix pour les applications modernes. La courbe d'apprentissage est modérée mais l'investissement se rentabilise rapidement.

GraphQL excelle dans les architectures avec de nombreux clients ayant des besoins variés. Pour une implémentation robuste, adoptez la pagination cursor-based pour les listes, les DataLoaders pour résoudre le problème N+1, et les persisted queries pour optimiser les performances en production. La sécurité est cruciale : limitez la profondeur des requêtes et désactivez l'introspection en production. Apollo Studio offre un excellent outillage de monitoring et de versioning de schéma. GraphQL et REST ne s'opposent pas : combinez-les selon les besoins de chaque endpoint de votre architecture pour une solution optimale et pragmatique.

Subscriptions temps réel

Les GraphQL Subscriptions permettent des mises à jour en temps réel via WebSockets. Le serveur notifie les clients abonnés à chaque mutation pertinente, sans polling. Apollo Server implémente les subscriptions avec graphql-ws (protocole recommandé en 2025, remplaçant subscriptions-transport-ws obsolète). Gérez la scalabilité des subscriptions avec un broker pub/sub (Redis) pour partager les événements entre plusieurs instances du serveur GraphQL.