Aller au contenu principal

API : REST vs GraphQL

· 4 minutes de lecture

Un écran qui affiche un utilisateur, ses derniers articles et leurs commentaires enchaîne, face à une API REST, plusieurs requêtes vers des endpoints distincts et reçoit au passage des champs dont il n'a pas l'usage. GraphQL inverse ce rapport en laissant le client décrire, en une seule requête, la forme exacte des données attendues. Les deux approches reposent sur des choix architecturaux distincts : leurs différences portent sur la manière d'adresser les données, sur la répartition du contrôle entre client et serveur, et sur la gestion du cache et des erreurs.

Qu'est-ce qu'une API REST ?​

REST (Representational State Transfer), formalisé par Roy Fielding en 2000, est un style architectural pour les systèmes distribués. Il repose sur l'identification des ressources via des URI, la manipulation de ces ressources à l'aide de méthodes HTTP standardisées (GET, POST, PUT, DELETE), et l'absence d'état côté serveur (statelessness).

REST favorise une séparation stricte entre client et serveur, permettant une évolutivité horizontale et une interopérabilité accrue. Les ressources sont représentées sous forme de documents (souvent JSON), et l'API expose un ensemble d'endpoints correspondant à des entités métier.

Principes clés REST​

  • Ressources identifiées par des URLs : chaque entité métier possède une URI unique
  • Stateless : chaque requête HTTP est indépendante, facilitant la scalabilité
  • Utilisation sémantique des méthodes HTTP : GET (lecture), POST (création), PUT/PATCH (modification), DELETE (suppression)
  • Format de réponse standardisé : JSON, XML, ou autres, selon le header Accept
  • Cacheabilité : possibilité d'utiliser le cache HTTP pour optimiser les performances

Exemple d'appel REST​

GET /users/123
Accept: application/json

Réponse typique :

{
"id": 123,
"name": "Alice",
"email": "alice@example.com"
}

Qu'est-ce que GraphQL ?​

GraphQL, introduit par Facebook en 2015, est un langage de requête et un runtime pour les API. Il propose une approche déclarative : le client décrit précisément la forme et la structure des données attendues, et le serveur répond en conséquence, via un unique endpoint.

GraphQL s'appuie sur un schéma fortement typé, défini côté serveur, qui décrit l'ensemble des types, des relations et des opérations (queries, mutations, subscriptions) disponibles. Cette introspection permet une documentation automatique et une validation statique des requêtes.

Principes clés GraphQL​

  • Un seul endpoint (généralement /graphql) : simplifie la gestion réseau et la sécurité
  • Requêtes déclaratives et flexibles : le client spécifie exactement les champs et relations désirés, limitant l'overfetching et l'underfetching
  • Schéma fortement typé : chaque type, champ et opération est explicitement défini, permettant la validation et l'autocomplétion
  • Agrégation de ressources : possibilité de récupérer des graphes de données complexes en une seule requête
  • Introspection : le schéma est auto-documenté et interrogeable dynamiquement

Exemple de requête GraphQL​

query {
user(id: "123") {
name
email
posts {
title
}
}
}

Réponse typique :

{
"data": {
"user": {
"name": "Alice",
"email": "alice@example.com",
"posts": [
{ "title": "Premier post" },
{ "title": "Second post" }
]
}
}
}

Modélisation et sémantique des données​

REST modélise les entités métier comme des ressources indépendantes, accessibles via des URI. Les relations entre ressources sont généralement exprimées par des liens ou des sous-routes (ex : /users/123/posts).

GraphQL modélise les données comme un graphe typé : chaque type peut référencer d'autres types, et les requêtes peuvent naviguer dans ce graphe de manière récursive. Cela permet d'exprimer des relations complexes et d'optimiser la récupération des données.

Comparaison des concepts​

CritèreRESTGraphQL
EndpointPlusieurs (par ressource)Un seul
Format de réponseFixe (souvent tout l'objet)Flexible (le client choisit)
OverfetchingOui (données inutiles)Non (le client choisit les champs)
UnderfetchingOui (requêtes multiples nécessaires)Non
DocumentationSwagger, OpenAPISchéma introspectif, autogénéré
VersioningPar URL ou headerÉvolution incrémentale du schéma
ErreursCodes HTTPObjet d'erreur structuré dans la réponse
TypageNon imposé (contrat explicite si OpenAPI)Fort (contrats explicites)
DécouverteVia une documentation externe (OpenAPI)Automatique, via introspection

Gestion des erreurs et robustesse​

REST s'appuie sur les codes de statut HTTP pour signaler les erreurs (404, 500, etc.), ce qui permet une gestion standardisée mais parfois peu granulaire.

GraphQL encapsule les erreurs dans la réponse JSON, permettant de signaler des erreurs partielles (ex : certains champs en erreur, d'autres valides), ce qui améliore la résilience côté client.

Avantages et limites​

REST​

  • Avantages : standardisation HTTP, écosystème étendu
  • Limites : overfetching et underfetching, multiplication des endpoints

GraphQL​

  • Avantages : flexibilité des requêtes, moins de requêtes réseau, typage fort et introspection
  • Limites : courbe d'apprentissage, complexité côté serveur, pas de cache HTTP natif

Quand choisir l'un ou l'autre ?​

  • REST : API orientées ressources (CRUD), forte compatibilité, besoin de cache HTTP
  • GraphQL : applications aux vues composites, besoins mobiles, agrégation de données, évolutivité du schéma

Conclusion​

REST couvre la majorité des API orientées ressources et tire parti du cache HTTP ; GraphQL répond aux besoins de flexibilité des requêtes et de réduction du nombre d'échanges, au prix d'une complexité accrue côté serveur. Le choix dépend du contexte technique et des besoins métier.