# X-WP-Total et X-WP-TotalPages : paginer un catalogue sans requête de plus

> Deux en-têtes fournis gratuitement par l'API REST évitent une requête de comptage séparée pour construire une pagination fiable côté front.

- Auteur : WordPress Développement
- Publié le : 2022-04-30
- Mis à jour le : 2022-04-30
- Catégorie : Headless & API
- URL : https://www.wpmoderne.fr/headless/x-wp-total-x-wp-totalpages-paginer-catalogue/

## L’essentiel

- X-WP-Total indique le nombre total d'éléments correspondant aux filtres
- X-WP-TotalPages se déduit du total et du paramètre per_page
- Aucune requête supplémentaire n'est nécessaire pour connaître ces valeurs

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

> L'essentiel à retenir : X-WP-Total indique le nombre total d'éléments correspondant aux filtres ; X-WP-TotalPages se déduit du total et du paramètre per_page ; Aucune requête supplémentaire n'est nécessaire pour connaître ces valeurs

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.