Vous lancez un nouveau projet digital et la question tombe : REST ou GraphQL ? Ce choix d’architecture API peut paraître très technique, mais il a un impact direct sur la vitesse de développement, les performances de votre application et les coûts de maintenance à long terme.
Bonne nouvelle : il n’y a pas de mauvaise réponse universelle. Tout dépend de votre contexte. Voici un guide pragmatique pour y voir clair.
Rappel : REST et GraphQL en quelques mots
REST (Representational State Transfer)
REST est le standard historique du web. Chaque ressource (utilisateur, produit, commande…) est accessible via une URL dédiée, et on utilise les méthodes HTTP classiques : GET, POST, PUT, DELETE.
Par exemple, pour récupérer un utilisateur et ses commandes, vous faites deux appels :
GET /api/users/42GET /api/users/42/orders
C’est simple, prévisible et largement adopté depuis plus de 20 ans.
GraphQL
GraphQL, créé par Facebook en 2015, adopte une approche différente. Il expose un seul endpoint et c’est le client qui décrit précisément les données dont il a besoin dans sa requête.
Une seule requête peut récupérer l’utilisateur et ses commandes, en ne demandant que les champs nécessaires. Pas plus, pas moins.
Les avantages de REST
- Simplicité — Le modèle est intuitif. Chaque URL correspond à une ressource. N’importe quel développeur comprend le fonctionnement en quelques minutes.
- Caching HTTP natif — Les réponses REST profitent directement du cache des navigateurs, des CDN et des proxys. C’est un gain de performance considérable sans effort supplémentaire.
- Standardisation — Les codes de statut HTTP (200, 404, 500…) sont universels. La documentation, les conventions et les bonnes pratiques sont matures et bien établies.
- Outillage riche — Swagger/OpenAPI, Postman, les générateurs de SDK… L’écosystème d’outils autour de REST est vaste et éprouvé.
Les avantages de GraphQL
- Flexibilité des requêtes — Le client demande exactement ce dont il a besoin. Une application mobile peut demander moins de champs qu’un dashboard web, avec la même API.
- Un seul endpoint — Plus besoin de jongler avec des dizaines d’URLs. Tout passe par un point d’entrée unique, ce qui simplifie la gestion côté client.
- Pas d’over-fetching — Fini les réponses API qui renvoient 50 champs quand vous n’en utilisez que 3. Vous économisez de la bande passante et améliorez les performances.
- Typage fort et introspection — Le schéma GraphQL sert de documentation vivante. Les outils comme GraphiQL permettent d’explorer l’API de manière interactive.
Comparaison côte à côte
| Critère | REST | GraphQL |
|---|---|---|
| Courbe d’apprentissage | Faible | Moyenne |
| Caching | Natif (HTTP) | Complexe (nécessite Apollo, etc.) |
| Nombre d’endpoints | Multiple | Unique |
| Over-fetching | Fréquent | Résolu par design |
| Under-fetching | Fréquent (appels multiples) | Résolu par design |
| Upload de fichiers | Simple | Plus complexe |
| Monitoring / debugging | Simple (codes HTTP) | Nécessite un outillage dédié |
| Documentation | OpenAPI / Swagger | Schéma auto-documenté |
| Écosystème | Très mature | En forte croissance |
Les limites à connaître
Côté REST
- Over-fetching et under-fetching — Soit l’API renvoie trop de données, soit pas assez, ce qui oblige à multiplier les appels. C’est le problème classique N+1.
- Rigidité — Ajouter un champ ou modifier une réponse peut nécessiter une nouvelle version de l’API, ce qui alourdit la maintenance.
- Multiplication des endpoints — Sur un projet complexe, on peut se retrouver avec des centaines de routes à maintenir et documenter.
Côté GraphQL
- Complexité accrue — La mise en place initiale (schéma, résolveurs, gestion des erreurs) est plus lourde qu’un simple CRUD REST.
- Caching plus difficile — Les requêtes POST sur un endpoint unique ne profitent pas du cache HTTP. Il faut des solutions dédiées côté client (Apollo, urql) et serveur.
- Risque de requêtes coûteuses — Sans garde-fous, un client peut construire des requêtes imbriquées très profondes qui mettent le serveur à genoux. Il faut prévoir des limites de profondeur et de complexité.
- Monitoring moins évident — En REST, un
GET /usersqui retourne un 500 est facile à tracer. En GraphQL, toutes les requêtes passent par le même endpoint avec un code 200, même en cas d’erreur partielle.
Quand choisir REST ?
REST reste le meilleur choix dans plusieurs situations courantes :
- APIs publiques — Vos partenaires et développeurs tiers s’attendent à du REST. La courbe d’apprentissage est minimale et la documentation standardisée.
- Applications CRUD classiques — Un back-office, un site e-commerce standard, un CMS… Si vos opérations sont simples et prévisibles, REST fait le travail sans complexité superflue.
- Architecture microservices — La communication entre services internes est naturellement orientée ressources. REST, couplé à OpenAPI, offre des contrats d’interface clairs.
Quand choisir GraphQL ?
GraphQL prend tout son sens quand la flexibilité devient un vrai besoin :
- Applications mobiles — La bande passante est limitée et les écrans variés. Pouvoir demander uniquement les données nécessaires fait une vraie différence en performance et en expérience utilisateur.
- Dashboards et interfaces complexes — Quand une seule page affiche des données provenant de dizaines de sources, une requête GraphQL unique remplace des dizaines d’appels REST.
- Multiples consommateurs — Si une app mobile, un site web et un back-office consomment la même API avec des besoins différents, GraphQL évite de créer des endpoints spécifiques pour chacun.
Notre approche chez Shortcut
Chez Shortcut, nous sommes pragmatiques avant tout. Nous ne choisissons pas une technologie parce qu’elle est à la mode, mais parce qu’elle répond au besoin réel du projet.
Dans la majorité des cas, REST est notre recommandation par défaut. C’est simple, éprouvé, et ça couvre 80 % des besoins sans ajouter de complexité inutile.
Mais quand un projet l’exige — interface riche avec des données imbriquées, multiples clients aux besoins très différents, besoin de flexibilité maximale — nous intégrons GraphQL avec plaisir. Nous maîtrisons les deux approches et savons les combiner intelligemment quand c’est pertinent.
L’important, c’est que le choix technique serve votre produit, pas l’inverse.
Besoin d’un avis sur votre architecture API ?
Que vous partiez de zéro ou que vous souhaitiez moderniser une API existante, nous pouvons vous aider à faire le bon choix et à le mettre en œuvre proprement.