2 en-têtes HTTP, déjà présents dans chaque réponse d’une collection REST, suffisent à construire une pagination complète côté front : X-WP-Total et X-WP-TotalPages. Beaucoup de développeurs découvrant l’API REST de WordPress cherchent pourtant à recréer ce comptage eux-mêmes, via une seconde requête dédiée, sans savoir que l’information est déjà là, gratuitement, dans la réponse qu’ils reçoivent.
Étape 1 : observer la réponse brute
curl -i "https://exemple.test/wp-json/wp/v2/posts?per_page=10&page=1"Parmi les en-têtes de la réponse, deux lignes apparaissent systématiquement sur toute route de collection standard : X-WP-Total: 247 et X-WP-TotalPages: 25. La première indique le nombre total d’éléments correspondant aux filtres appliqués à la requête, indépendamment de la pagination demandée. La seconde est directement dérivée de la première, divisée par la valeur de per_page et arrondie au nombre entier supérieur.
Étape 2 : lire ces en-têtes côté front
async function chargerPage(page) {
const reponse = await fetch(`https://exemple.test/wp-json/wp/v2/posts?per_page=10&page=${page}`);
const total = parseInt(reponse.headers.get('X-WP-Total'), 10);
const totalPages = parseInt(reponse.headers.get('X-WP-TotalPages'), 10);
const articles = await reponse.json();
return { articles, total, totalPages };
}
La plupart des bibliothèques HTTP côté navigateur ou côté serveur exposent facilement les en-têtes de réponse via une méthode comme headers.get(). Il suffit de lire ces deux valeurs une seule fois par page chargée pour disposer de tout ce qu’il faut afficher une pagination numérotée classique, sans jamais avoir à demander séparément un comptage.
Étape 3 : construire l’affichage de pagination
- Désactiver le bouton « page suivante » quand la page courante égale
totalPages - Afficher le nombre total de résultats à côté du filtre actif, pour donner un repère à l’utilisateur
- Générer les numéros de page affichés à partir de
totalPages, sans jamais dépasser cette valeur
Étape 4 : attention aux filtres qui changent le total
Ces deux en-têtes reflètent toujours le total correspondant aux filtres réellement appliqués à la requête courante, pas le total général du site. Une requête filtrée par catégorie ou par terme de recherche renverra un X-WP-Total propre à ce sous-ensemble de résultats. C’est exactement le comportement souhaité pour une pagination cohérente : changer de filtre côté front doit systématiquement relire ces en-têtes à nouveau, plutôt que de réutiliser une valeur mise en cache d’un filtre précédent.
Étape 5 : le cas des routes personnalisées
Ces en-têtes ne sont pas automatiques sur une route entièrement personnalisée qui n’hérite pas de WP_REST_Controller : un développeur qui construit sa propre route de collection doit les ajouter lui-même, via la méthode header() de l’objet WP_REST_Response retourné :
$reponse = new WP_REST_Response( $resultats );
$reponse->header( 'X-WP-Total', $total );
$reponse->header( 'X-WP-TotalPages', (int) ceil( $total / $par_page ) );
return $reponse;
En résumé
Les en-têtes X-WP-Total et X-WP-TotalPages, présents nativement sur toute collection exposée par un contrôleur REST standard de WordPress, évitent une requête de comptage séparée pour construire une pagination fiable côté front headless. Sur une route personnalisée, reproduire ce même mécanisme reste simple, à condition d’y penser dès la conception de la route plutôt que de laisser le front deviner une valeur qu’il ne peut pas connaître autrement.
