Lorsque l’on construit une architecture WordPress headless, une question revient presque systématiquement :
Faut-il utiliser l’API REST native de WordPress ou WPGraphQL ?
Les deux solutions permettent de connecter WordPress à des applications modernes comme Next.js, React ou des applications mobiles. Pourtant, leur fonctionnement est très différent.
Alors laquelle choisir pour votre projet ?
Dans cet article, nous allons comparer leurs avantages, leurs limites et leurs cas d’utilisation afin de vous aider à prendre la bonne décision.
Pourquoi a-t-on besoin d’une API dans une architecture headless ?
Dans une architecture WordPress classique, le thème affiche directement les contenus.
Dans une architecture headless, le frontend est séparé du CMS.
Le schéma devient alors :
WordPress
↓
API
↓
Next.js / React
↓
Visiteur
L’API sert donc de passerelle entre WordPress et le frontend.
Deux solutions dominent aujourd’hui :
- l’API REST WordPress ;
- WPGraphQL.
Qu’est-ce que l’API REST WordPress ?
L’API REST est intégrée nativement à WordPress.
Elle permet de récupérer les contenus via des URLs spécifiques.
Par exemple :
/wp-json/wp/v2/posts
Cette requête renvoie les articles au format JSON.
Chaque type de contenu possède généralement son propre endpoint :
- articles ;
- pages ;
- catégories ;
- médias ;
- utilisateurs.
L’API REST est aujourd’hui disponible sur pratiquement tous les sites WordPress.
Qu’est-ce que WPGraphQL ?
WPGraphQL est une extension WordPress qui ajoute une API GraphQL.
Contrairement à l’API REST, le frontend peut demander exactement les données dont il a besoin.
Exemple simplifié :
{
posts {
nodes {
title
slug
featuredImage {
node {
sourceUrl
}
}
}
}
}
Le serveur retourne uniquement les champs demandés.
Aucune donnée inutile n’est transmise.
La différence fondamentale
L’API REST fonctionne avec plusieurs endpoints.
Exemple :
/posts
/pages
/categories
/media
WPGraphQL fonctionne avec un point d’entrée unique :
/graphql
Le frontend construit ensuite ses propres requêtes.
C’est cette différence qui explique la plupart des avantages et inconvénients des deux approches.
Comparatif rapide
| Critère | API REST | WPGraphQL |
|---|---|---|
| Installation | Native | Plugin |
| Prise en main | Très simple | Plus technique |
| Flexibilité | Bonne | Excellente |
| Nombre de requêtes | Plus élevé | Plus faible |
| Performance | Bonne | Très bonne |
| Courbe d’apprentissage | Faible | Moyenne |
| Documentation | Très abondante | Bonne |
| Next.js | Très adapté | Excellent |
| React | Très adapté | Excellent |
| Gros projets | Correct | Excellent |
Les avantages de l’API REST
Simplicité
Aucune installation supplémentaire.
L’API est disponible immédiatement.
Documentation abondante
La majorité des tutoriels WordPress utilisent l’API REST.
Facilité de débogage
Une URL dans le navigateur permet souvent de voir directement les données retournées.
Compatibilité universelle
Pratiquement tous les frameworks et langages savent consommer une API REST.
Les limites de l’API REST
Multiplication des requêtes
Pour construire une page complexe, plusieurs appels peuvent être nécessaires :
- article ;
- image ;
- auteur ;
- catégories ;
- données personnalisées.
Sur-récupération des données
WordPress renvoie souvent davantage d’informations que nécessaire.
Le frontend reçoit parfois des dizaines de champs inutilisés.
Gestion des relations
Les contenus liés nécessitent souvent plusieurs appels API.
Les avantages de WPGraphQL
Une seule requête
Le frontend peut récupérer toutes les données nécessaires en une seule demande.
Contrôle total des données
Seuls les champs utiles sont récupérés.
Meilleures performances sur les gros projets
Les applications complexes bénéficient souvent d’un nombre réduit d’appels réseau.
Très apprécié dans l’écosystème React
GraphQL est largement utilisé dans les projets modernes.
Les limites de WPGraphQL
Installation supplémentaire
Le plugin doit être installé et maintenu.
Courbe d’apprentissage
GraphQL demande un temps d’adaptation.
Développement plus technique
Les équipes doivent maîtriser les requêtes GraphQL.
Exemple concret avec Next.js
Imaginons une page contenant :
- un article ;
- son auteur ;
- son image ;
- ses catégories.
Avec l’API REST
Plusieurs requêtes peuvent être nécessaires :
/posts
/users
/media
/categories
Avec WPGraphQL
Une seule requête suffit :
{
post {
title
content
author {
name
}
featuredImage {
node {
sourceUrl
}
}
categories {
nodes {
name
}
}
}
}
Pour un frontend moderne, cette approche est souvent plus élégante.
Quel impact sur les performances ?
La réponse dépend du projet.
Petit site vitrine
La différence sera généralement faible.
Blog d’entreprise
L’API REST est souvent suffisante.
Application SaaS
WPGraphQL devient intéressant.
Plateforme complexe
WPGraphQL prend généralement l’avantage.
La performance dépend également :
- du cache ;
- de l’hébergement ;
- de l’architecture globale ;
- du frontend.
Quel choix pour les projets IA ?
Les deux solutions permettent :
- d’alimenter un chatbot ;
- de créer un système RAG ;
- d’indexer des contenus ;
- d’exploiter des données structurées.
Cependant, WPGraphQL offre souvent davantage de souplesse lorsqu’il faut récupérer des contenus complexes ou fortement liés.
Pour des assistants IA ou des recherches sémantiques avancées, il est souvent apprécié des équipes de développement.
Quelle solution choisir ?
Choisissez l’API REST si :
- vous débutez avec le headless ;
- votre projet est relativement simple ;
- vous souhaitez limiter les dépendances ;
- vous privilégiez la simplicité.
Choisissez WPGraphQL si :
- vous utilisez fortement React ou Next.js ;
- vous développez une application complexe ;
- vous avez beaucoup de relations entre contenus ;
- vous souhaitez optimiser les requêtes.
Mon retour d’expérience
Pour la majorité des projets WordPress headless, l’API REST reste une excellente porte d’entrée.
Elle est simple, robuste et parfaitement adaptée aux sites vitrines, blogs et plateformes de contenu.
En revanche, dès que l’application devient plus ambitieuse, avec des données fortement connectées ou des interfaces complexes, WPGraphQL apporte un vrai confort de développement.
Le choix ne dépend donc pas uniquement de la technologie, mais surtout de la complexité du projet.
Conclusion
L’API REST et WPGraphQL poursuivent le même objectif : permettre à WordPress d’alimenter un frontend moderne.
L’API REST privilégie la simplicité et la compatibilité.
WPGraphQL privilégie la flexibilité et l’optimisation des requêtes.
Pour un premier projet headless, l’API REST constitue souvent le meilleur point de départ. Pour des applications React ou Next.js plus avancées, WPGraphQL devient rapidement une solution très séduisante.
L’essentiel est de choisir l’outil le plus adapté aux besoins réels du projet et non celui qui semble le plus moderne.