L’API REST native de WordPress couvre bien des besoins, mais elle impose une structure fixe : chaque endpoint renvoie un ensemble de champs prédéfini, à charge pour le client de composer plusieurs requêtes pour assembler la donnée dont il a réellement besoin. WPGraphQL propose une approche différente, construite autour d’un principe simple : le client décrit exactement ce qu’il veut recevoir, ni plus ni moins.
Ce plugin, gratuit et open source, expose l’intégralité du contenu WordPress via un unique endpoint GraphQL. Il s’est imposé comme la référence de l’écosystème headless WordPress, notamment porté par son adoption dans des frameworks comme Gatsby ou, plus tard, Faust.js. Voici comment démarrer.
Installation et premier accès
WPGraphQL s’installe comme n’importe quel plugin WordPress, depuis le répertoire officiel ou en le téléversant manuellement. Une fois activé, il expose un unique endpoint à l’adresse /graphql, capable de répondre à toutes les requêtes, contrairement à l’API REST qui multiplie les routes par type de contenu.
Le plugin embarque également GraphiQL, un IDE interactif accessible directement dans l’administration WordPress (menu GraphQL > GraphiQL IDE). Cet outil affiche la documentation complète du schéma, avec autocomplétion, ce qui permet d’explorer les types disponibles sans avoir à consulter une documentation externe.
Une première requête
Voici une requête GraphQL typique, qui récupère les cinq derniers articles avec leur titre, leur extrait, leur date et leur image mise en avant :
query DerniersArticles {
posts(first: 5) {
nodes {
title
slug
date
excerpt
featuredImage {
node {
sourceUrl
altText
}
}
}
}
}Cette requête unique remplace ce qui, en REST, aurait nécessité un appel vers wp/v2/posts combiné à _embed pour l’image, avec en prime le risque de récupérer des champs inutiles. En GraphQL, la réponse contient exactement, et uniquement, les champs demandés dans la requête.
Pourquoi c’est un vrai gain par rapport à REST
Deux problèmes classiques de REST disparaissent avec GraphQL :
- Le sur-fetching — recevoir des champs inutiles qu’on ne consultera jamais, ce qui alourdit chaque réponse
- Le sous-fetching — devoir enchaîner plusieurs requêtes pour assembler une donnée complète, le fameux problème du N+1
Avec GraphQL, une seule requête peut traverser le graphe de données : récupérer un article, son auteur, ses catégories et les articles liés de cet auteur, tout en un aller-retour réseau. Voici un exemple qui va plus loin, en récupérant l’auteur et les catégories d’un article précis identifié par son slug :
query ArticleComplet($slug: ID!) {
post(id: $slug, idType: SLUG) {
title
content
author {
node {
name
avatar {
url
}
}
}
categories {
nodes {
name
slug
}
}
}
}Requêter depuis un frontend JavaScript
Aucun outillage complexe n’est requis pour commencer : une simple requête fetch en méthode POST suffit, en envoyant la requête GraphQL dans le corps de la requête HTTP :
const reponse = await fetch( 'https://exemple.fr/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify( {
query: `
query {
posts(first: 5) {
nodes { title slug }
}
}
`,
} ),
} );
const { data } = await reponse.json();Pour des projets plus ambitieux, des clients dédiés comme Apollo Client ou urql apportent une gestion de cache et d’état bien plus poussée, particulièrement utile dans des applications React ou Vue complexes.
Ne sous-estimez pas GraphiQL IDE : c’est souvent en explorant le schéma dans cet outil, avant même d’écrire une ligne de code frontend, qu’on repère la bonne structure de requête et qu’on évite des allers-retours inutiles avec l’équipe backend.
Les limites à connaître
WPGraphQL n’est pas magique : le schéma généré reflète la structure native de WordPress, et exposer des champs personnalisés (ACF, métadonnées custom) demande une configuration supplémentaire, que nous détaillerons dans un prochain article dédié à WPGraphQL for ACF. Autre point d’attention : contrairement à REST, disponible nativement, WPGraphQL reste un plugin tiers à maintenir et à mettre à jour, même si son adoption large en fait un choix de confiance pour la majorité des projets headless.
En résumé
WPGraphQL apporte une flexibilité que l’API REST native ne peut pas offrir par conception : des requêtes sur mesure, un unique endpoint, et un IDE d’exploration intégré qui accélère considérablement le développement d’un frontend headless. Pour un projet avec des besoins de données complexes ou imbriqués, c’est souvent le choix le plus pertinent face à REST.
