API REST vs GraphQL : comprendre les différences pour bien choisir

API REST vs GraphQL : la différence qui change tout (et pas celle qu'on croit)

Un développeur m'a envoyé un message la semaine dernière. Il venait de passer trois jours à optimiser une page produit qui chargeait cinq appels REST en cascade. Réduire à deux, puis à un seul. Le chargement est passé de 2,4 secondes à 900 millisecondes. Il était content. Puis quelqu'un lui a dit : « avec GraphQL, tu aurais eu ça en une requête, sans rien optimiser ».

Il m'a demandé si c'était vrai. Et franchement, la réponse honnête est : oui et non. Oui sur le principe. Non sur tout le reste.

Parce que la comparaison REST vs GraphQL qu'on lit partout — « REST fait ci, GraphQL fait ça » — passe à côté du vrai sujet. Le débat intéressant n'est pas quel protocole est meilleur. C'est : quel problème vous avez, et lequel des deux le résout sans en créer trois nouveaux.

REST vs GraphQL : de quoi parle-t-on vraiment ?

Beaucoup d'articles ouvrent avec « REST est un style architectural, GraphQL est un langage de requête ». C'est exact et ça n'aide personne.

La différence utile tient en une phrase : avec REST, vous décidez côté serveur quelle forme a une réponse. Avec GraphQL, vous laissez le client décider.

Ce que REST impose (et pourquoi c'est confortable)

REST part d'une idée simple : une URL = une ressource. GET /users/42 renvoie un utilisateur. POST /orders en crée une. Les verbes HTTP portent l'intention, les codes de statut portent le résultat.

Le confort vient de là : n'importe quel intermédiaire — navigateur, CDN, proxy d'entreprise — comprend ces règles sans rien savoir de votre métier. Une réponse GET peut être mise en cache par l'infrastructure, souvent sans une ligne de code.

L'inconvénient suit la même logique. Pour afficher l'utilisateur 42 avec ses commandes, il faut deux appels. Avec ses commandes et la photo de chaque produit, trois. Avec le nom du vendeur de chaque produit, quatre. Le fameux N+1 des clients mobiles, que tout le monde connaît et que personne n'aime.

Ce que GraphQL change vraiment

GraphQL renverse la décision. Le schéma expose un graphe de données typées, et le client écrit exactement ce qu'il veut :

query {
  user(id: 42) {
    name
    orders {
      total
      product { photoUrl }
    }
  }
}

Une requête, un aller-retour, une réponse sur mesure. Ce n'est pas magique — derrière, le serveur exécute probablement les mêmes requêtes base de données. Mais le réseau, lui, souffle.

Les limites concrètes de REST que GraphQL prétend résoudre

Sur mon ancien projet e-commerce, la page d'accueil mobile tirait 8 endpoints différents. Temps total mesuré au premier rendu : 3,1 secondes en 4G correcte. L'équipe mobile se plaignait depuis six mois.

Le problème n'était pas REST en soi. C'était ce qu'on avait construit dessus.

• Over-fetching : le endpoint /products renvoyait 34 champs par produit. L'app mobile en utilisait 6. On transportait 82 % de données mortes.
• Under-fetching : impossible d'obtenir une commande et son utilisateur en un seul appel. Il fallait deux requêtes, puis une troisième pour la livraison.
• Prolifération des endpoints : une nouvelle maquette = un nouveau endpoint. Après deux ans, on en avait 61. Personne ne savait lesquels étaient encore utilisés.

Ces trois douleurs sont réelles. GraphQL les traite directement. Mais elles viennent d'un choix de conception, pas du protocole REST lui-même — et c'est là que la plupart des comparatifs dérapent.

Ce que personne ne vous dit sur GraphQL

Voilà le passage qu'on ne trouve presque jamais dans les articles « REST vs GraphQL ». Les avantages sont réels. Le coût aussi.

Le cache : là où ça fait mal

En REST, un proxy peut mettre GET /products/12 en cache pendant une heure. Gratuit, standardisé. En GraphQL, presque toutes les requêtes passent en POST /graphql avec un corps différent. Aucun cache HTTP générique ne peut deviner si deux requêtes sont équivalentes.

Résultat : vous implémentez du cache applicatif côté serveur, par résolveur ou par entité. J'ai vu une équipe y consacrer quatre sprints avant d'obtenir des performances comparables à ce que le CDN faisait tout seul en REST.

Requêtes coûteuses et sécurité

Un client curieux peut écrire une requête profondément imbriquée — utilisateur → commandes → produits → vendeurs → commandes → produits — qui épuise votre base. En REST, les endpoints ont une forme fixe : ce genre d'improvisation n'existe pas.

La parade existe (analyse de profondeur, calcul de coût, limite de complexité), mais elle doit être construite et maintenue. Ce n'est pas livré avec.

Tableau comparatif : REST et GraphQL, point par point

Critère	REST	GraphQL
Qui décide de la forme de la réponse	Le serveur	Le client
Nombre d'allers-retours pour un écran complexe	Multiple, souvent 4 à 8	Un seul, en général
Cache HTTP standard	Fonctionne nativement	Nécessite une couche applicative
Versionnement	Par URL ou en-tête	Par évolution du schéma, sans version
Courbe d'apprentissage côté serveur	Faible	Élevée (schéma, résolveurs, N+1)
Surface d'attaque	Endpoints figés, surface connue	Requêtes libres, à encadrer
Outillage de test	Mature depuis longtemps	Bon, mais dépend du serveur
Adoption par des équipes non techniques	Évidente (URL, cURL)	Nécessite un client ou un playground adapté

Ce tableau ne dit pas qui gagne. Il dit où chaque option coûte.

Quand choisir l'un, quand choisir l'autre

Mon avis, après avoir livré les deux en production : la question n'est pas « le meilleur », c'est qui consomme vos données.

GraphQL devient pertinent si…

• Vous avez plusieurs clients (iOS, Android, web, partenaires) avec des besoins différents sur les mêmes données.
• Vos écrans dépendent de relations profondes : commandes, produits, utilisateurs, avis, transports.
• Votre équipe front est autonome et sait lire un schéma.
• Vous souffrez déjà de N+1 côté client et vous l'avez mesuré.

Restez en REST si…

• Votre API est publique et consommée par des inconnus. Les endpoints prévisibles et le cache standard valent de l'or.
• Vous avez peu de relations entre ressources.
• Votre équipe backend est petite et n'a pas le temps de construire la couche sécurité/cache de GraphQL.
• Le trafic est majoritairement des GET simples, très cachables.

Faire cohabiter REST et GraphQL sur le même backend

C'est la partie que les comparatifs oublient. Et pourtant, dans mon expérience, c'est la réponse la plus courante.

Sur le projet e-commerce dont je parlais plus haut, on n'a pas migré. On a ajouté une couche GraphQL devant les mêmes services métier, et exposé trois requêtes aux clients mobiles : la page d'accueil, la fiche produit, le tunnel de commande. Tout le reste — back-office, exports, webhooks partenaires — est resté en REST.

Résultat mesuré après trois mois : le temps de rendu de l'accueil mobile est passé de 3,1 secondes à 1,4 seconde. Les appels REST historiques n'ont pas bougé. Aucune réécriture massive.

Le vrai apprentissage : GraphQL s'ajoute, il ne remplace pas. Tant qu'on le traite comme un remplacement, la migration paraît titanesque. Traité comme une façade sur l'existant, elle devient raisonnable.

Trois erreurs que j'ai faites (pour que vous les évitiez)

Vouloir tout exposer dans le schéma

Première version : schéma complet, chaque entité, chaque champ. Le playground était magnifique. En production, des requêtes imbriquées à six niveaux ont saturé la base pendant un pic. On a mis deux semaines à ajouter un calcul de coût et une limite de profondeur. J'aurais dû commencer par là.

Négliger le cache dès le début

On a livré sans stratégie de cache serveur. Chaque requête frappait la base. Les performances étaient bonnes en développement et moyennes en production. Corriger après coup coûte trois fois plus cher.

Sous-estimer la marche pour l'équipe backend

Deux développeurs sur quatre ont mis un mois à être à l'aise avec les résolveurs et la gestion du N+1. Ce n'est pas insurmontable, mais ce n'est pas « une après-midi », contrairement à ce que laisse penser la documentation d'introduction.

Questions qu'on me pose souvent

GraphQL, c'est quoi ?

GraphQL est un langage de requête pour API, créé chez Facebook et rendu public. Le serveur expose un schéma typé qui décrit toutes les données disponibles et leurs relations. Le client écrit ensuite une requête qui demande exactement les champs dont il a besoin — ni plus, ni moins — et reçoit une réponse qui correspond au schéma de sa requête.

Pour un tuto GraphQL, par où commencer ?

Commencez par écrire un schéma à la main, même minuscule : un type User avec deux champs. Puis un résolveur qui renvoie une valeur statique. Vous verrez immédiatement ce qui distingue GraphQL de REST : le schéma est la source de vérité, et les résolveurs ne font que répondre aux champs demandés. Le reste — scalaires, fragments, mutations, abonnements — s'ajoute après. Ne commencez pas par un schéma complet de votre base de données, c'est le meilleur moyen d'abandonner au bout d'une semaine.

GraphQL est-il plus rapide que REST ?

Pas intrinsèquement. GraphQL réduit le nombre d'allers-retours réseau et la taille du payload, ce qui améliore souvent le temps perçu côté client. Côté serveur, il peut être plus lent qu'un endpoint REST bien optimisé, parce qu'il faut résoudre un graphe à la volée. Un GET /users/42 restera, dans presque tous les cas, plus rapide qu'une requête GraphQL équivalente.

La vraie question à se poser

Le débat REST vs GraphQL ne se tranche pas sur le papier. Il se tranche quand vous regardez vos écrans, vos clients et vos mesures.

Si vos équipes front passent leur temps à demander des endpoints sur mesure, et que vous avez les moyens de construire la couche cache et sécurité, GraphQL va vous faire gagner beaucoup — beaucoup de temps, et beaucoup de discussions. Si votre API est publique, simple et largement cachée par l'infrastructure, fuyez la complexité : REST fait le travail depuis des années, et il continue.

Et cette question, personne ne se la pose assez tôt : combien de temps votre équipe peut-elle réellement investir dans une nouvelle pile ? Ce n'est pas un détail technique. C'est souvent la seule réponse qui compte.