Nous avons tous déjà dû choisir entre API RESTful et GraphQL au démarrage d’un projet. Sur le papier, les deux délivrent des données sur le web. En pratique, elles conditionnent notre manière de modéliser, d’évoluer, de sécuriser et d’optimiser les échanges. Dans cet article, nous clarifions les différences clés, partageons des retours concrets, et posons des critères simples pour faire le bon choix sans dogme.
Ce Que Sont REST Et GraphQL
Principes De REST
REST repose sur des ressources adressables (URI), des verbes HTTP (GET, POST, PUT, PATCH, DELETE) et des statuts standardisés (2xx, 4xx, 5xx). On s’appuie sur les en-têtes HTTP (Cache-Control, ETag, Vary) pour la mise en cache et sur des conventions comme OpenAPI pour décrire le contrat. Un design REST mature expose des liens (HATEOAS) et respecte l’idempotence. En clair, on structure le monde en ressources, on manipule leurs représentations, et le protocole HTTP porte beaucoup d’intelligence côté réseau.
Notions Clés De GraphQL
GraphQL propose un schéma typé (SDL) décrivant types, champs et relations. Le client déclare exactement les champs dont il a besoin dans une unique requête. Les mutations modifient les données, et les subscriptions gèrent le temps-réel via WebSocket ou SSE. Les réponses incluent potentiellement un bloc data et un bloc errors. Côté serveur, des resolvers assemblent la donnée depuis une ou plusieurs sources. Le schéma est autodocumenté et évolutif (dépréciations, non-breaking changes), ce qui séduit les équipes produits et front.
Différences De Conception Et D’Évolution
Modélisation, Versionnage Et Compatibilité
Avec REST, nous modélisons des ressources stables (users, orders, invoices) et des endpoints cohérents. Le versionnage est explicite (/v1, /v2) ou via en-têtes. On anticipe tôt la granularité et l’agrégation (sinon on crée des endpoints composites ou un BFF). La compatibilité se gère en maintenant plusieurs versions, souvent lourdes à opérer.
Avec GraphQL, nous modélisons un graphe métier. Le schéma est extensible: on ajoute des champs, on annote @deprecated, et on évite les ruptures. Pas de version majeure en cascade: on mène des migrations progressives pilotées par l’usage (analytics de champs) et des garde-fous CI qui valident les changements (ex: checks de breaking changes et codegen pour les clients).
Gestion Des Erreurs Et Contrats
REST s’appuie sur la sémantique HTTP: 200, 201, 204, 400, 404, 409, 422, 429, 500… avec des bodies normalisés (ex: application/problem+json). Les proxys, passerelles et observabilités comprennent nativement ces codes.
GraphQL renvoie souvent 200 même en cas d’erreurs de champs, avec un tableau errors détaillé. C’est précis côté client, mais ça brouille parfois la supervision si on ne mappe pas les erreurs applicatives en statuts HTTP au niveau passerelle. Le contrat côté REST se publie via OpenAPI/Swagger: côté GraphQL, le schéma et l’introspection font office de source de vérité, complétés par des descriptions et des directives.
Performance Et Réseau
Sur- Et Sous-Récupération, Agrégation Des Données
Sur mobile ou réseaux fluctuants, le sur- et sous-récupération pèsent lourd. En REST, une vue complexe peut nécessiter 3 à 6 appels (profil, commandes, recommandations). On contourne avec des endpoints dédiés, du BFF, ou des paramètres de champs (?fields=). GraphQL tranche ce problème en laissant le client sélectionner exactement les champs d’un graphe en un aller-retour. En revanche, il faut maîtriser l’effet N+1 dans les resolvers (DataLoader, batching) pour éviter de déplacer le problème côté serveur.
Pour l’agrégation, REST mise sur la composition au backend ou une passerelle API: GraphQL l’intègre nativement via un gateway/federation qui orchestre plusieurs services. Là où REST capitalise sur la simplicité et la cacheabilité des ressources, GraphQL optimise la conversation client-API, surtout pour des interfaces riches et évolutives.
Caching, Pagination Et Intégration CDN
REST bénéficie du cache HTTP hors de la boîte: ETag/If-None-Match, Cache-Control (max-age, s-maxage, stale-while-revalidate), validation conditionnelle, et CDN très efficaces. La pagination est variée (offset/limit), avec une tendance aux curseurs pour la stabilité.
GraphQL peut aussi tirer parti d’un CDN, mais il faut y penser: persisted queries (APQ) avec GET et clés de cache stables, TTL maîtrisés, et parfois un split par route (ex: /graphql-public en GET pour lecture). Côté client, des caches normalisés (Apollo/Relay) dédupliquent et régénèrent le store. La pagination par curseur est de facto (Relay spec), robuste pour les flux dynamiques. En résumé: REST excelle sur le cache « réseau »: GraphQL brille avec un cache « client » riche et des requêtes ciblées.
Sécurité Et Observabilité
Auth, Autorisation Et Quotas
REST et GraphQL partagent les mêmes briques: OAuth 2.0/OIDC, JWT, API keys, mTLS si nécessaire. La différence se joue dans la granularité. En REST, nous appliquons des scopes par ressource/endpoint. En GraphQL, on peut pousser l’autorisation au champ et au resolver (règles ABAC/RBAC), pratique pour masquer des données sensibles selon le contexte. Les quotas et plans tarifaires restent plus intuitifs côté REST (par appel): côté GraphQL, on bascule souvent vers une tarification par « coût de requête » ou par opération persistée.
Complexité Des Requêtes, Rate Limiting Et Monitoring
GraphQL introduit un nouveau risque: les requêtes trop profondes ou trop coûteuses. Nous limitons la profondeur, calculons un coût (graphql-query-complexity), mettons des timeouts, et privilégions les opérations persistées/allowlistées. Le rate limiting s’exprime alors en jetons par coût plutôt que par simple nombre d’appels. En REST, le rate limiting reste classique (token bucket, leaky bucket) par IP, clé, utilisateur.
Pour l’observabilité, nous instrumentons OpenTelemetry, corrélons les requêtes avec des IDs, traçons les resolvers (Apollo tracing) et surveillons les erreurs GraphQL même quand le HTTP renvoie 200. Logs structurés, métriques (latence P95/P99, hit ratio cache), et alertes 4xx/5xx demeurent indispensables sur les deux modèles.
Outils, Écosystème Et Apprentissage
Frameworks, Clients Et Outils De Test
Pour REST, les frameworks populaires abondent: Express/Fastify, Spring Boot, Django/DRF, FastAPI, Laravel. Côté clients: Axios, Retrofit, Fetch et consorts. Pour GraphQL, nous avons Apollo Server, Yoga, Mercurius, Hot Chocolate, Hasura: côté clients, Apollo Client, Relay, urql, graphql-request. Les tests se font avec Jest/Supertest, Newman, ou des libs dédiées GraphQL: la génération de types est bien couverte (OpenAPI Generator, GraphQL Code Generator).
Documentation, Découverte Et Playgrounds
REST rayonne via OpenAPI/Swagger UI et des portails développeurs. La découverte est explicite et adaptée au public externe. GraphQL mise sur l’introspection, GraphiQL, Apollo Sandbox/Studio et des descriptions riches dans le schéma. En prod, nous pouvons limiter ou désactiver l’introspection publique, tout en gardant des sandboxes sécurisés. Postman, Insomnia et Hoppscotch gèrent désormais très correctement GraphQL comme REST.
Faire Le Bon Choix
Critères Pratiques Selon Le Contexte
Nous pouvons trancher avec quelques questions très concrètes. L’interface cliente est-elle complexe, avec des écrans qui croisent beaucoup de sources? GraphQL simplifie et stabilise le dialogue, surtout sur mobile. Le domaine est-il simple, très cacheable, exposé publiquement (catalogues, contenus)? REST gagne en simplicité, compatibilité CDN, et lisibilité des erreurs. L’équipe maîtrise-t-elle l’un des deux? Le facteur expertise pèse sur le time-to-market. Avons-nous déjà un portail API et des consommateurs tiers? REST reste la norme de facto pour les intégrations externes. Besoin de temps-réel? Les deux savent faire, mais les subscriptions GraphQL offrent une expérience homogène côté schéma.
Un exemple parlant: pour une app qui charge profil, commandes récentes et panier en un écran, GraphQL évite la succession d’appels et réduit le poids des réponses en ne ramenant que les champs utiles. À l’inverse, pour une API publique de produits hautement cacheable, un REST bien paramétré avec ETag et CDN sert des millions de requêtes à coût dérisoire.
Approches Hybrides Et Migration Progressive
Nous n’avons pas à choisir une seule voie. Beaucoup d’équipes gardent REST pour l’externe et ajoutent un gateway GraphQL pour les apps web/mobile internes. Une approche BFF fonctionne bien: REST pour les ressources simples, GraphQL pour assembler l’expérience. Pour migrer, on peut commencer par un schéma en lecture qui enveloppe les endpoints REST existants, monitorer l’usage des champs, puis introduire des mutations. Apollo Federation ou GraphQL Mesh aident à composer plusieurs services. Côté gouvernance, des checks CI de schéma, des métriques d’usage et des dépréciations pilotées par données évitent le big bang. Et si nous restons 100% REST, les paramètres de champs, les endpoints de composition et un OpenAPI propre couvrent 90% des besoins sans douleur.
Conclusion
API RESTful et GraphQL ne s’opposent pas, elles se complètent. REST brille par sa simplicité, sa sémantique HTTP et son intégration naturelle aux CDN. GraphQL excelle pour des UIs riches, la réduction des allers-retours et l’évolution guidée par le schéma. Le bon choix tient à notre contexte: complexité métier, profils de clients, contraintes de cache et maturité d’équipe. En gardant l’esprit pragmatique, voire en combinant les deux, nous livrons plus vite, plus robuste, et au meilleur coût réseau.
