Sur un front qui affiche une grille de vignettes d’articles, j’ai un jour inspecté la taille de la réponse renvoyée par /wp-json/wp/v2/posts : plus de 40 Ko pour dix articles, alors que la page n’affichait que le titre, l’extrait, la date et une image. Le contenu complet, le guid, les liens _links détaillés, les champs de méta box non filtrés : tout partait dans la réponse, pour rien. Le paramètre _fields résout exactement ce problème.
Il s’agit d’un paramètre de requête global, disponible sur toutes les routes natives de l’API REST WordPress, qui filtre la réponse pour ne renvoyer que les champs demandés. Contrairement à ce qu’on pourrait croire, il n’accélère pas la requête côté base de données : il réduit uniquement la taille de la réponse JSON transmise au client.
Utilisation de base
Le paramètre accepte une liste de noms de champs séparés par des virgules. Pour une liste de vignettes, on ne garde généralement que l’identifiant, le titre, l’extrait, la date et le slug :
GET /wp-json/wp/v2/posts?_fields=id,slug,title,excerpt,dateLa réponse ne contient alors plus que ces cinq clés par article, au lieu de la trentaine renvoyées par défaut (contenu complet, guid, modified_gmt, ping_status, template, meta, _links…). Sur une liste paginée à dix ou vingt éléments, l’économie de poids est immédiate.
Accéder aux champs imbriqués
Certains champs de la réponse, comme title ou excerpt, sont eux-mêmes des objets contenant une clé rendered et parfois raw. On peut cibler précisément une sous-clé avec la notation pointée :
GET /wp-json/wp/v2/posts?_fields=id,slug,title.rendered,excerpt.renderedCette précision évite de conserver title.raw, qui n’existe de toute façon que pour les utilisateurs autorisés à éditer le contenu, ou l’objet title entier si seul le rendu HTML intéresse le front.
Combiner _fields avec _embed
Sur beaucoup de projets, la liste d’articles doit aussi afficher l’image mise en avant et le nom de l’auteur, deux données récupérées habituellement via le paramètre _embed. Sans filtrage, _embed ajoute une clé _embedded volumineuse, avec l’objet média complet (toutes les tailles d’image générées) et l’objet auteur complet.
La combinaison des deux paramètres reste possible, mais avec une subtilité : il faut inclure explicitement _links ou _embedded dans la liste de _fields pour que les données imbriquées survivent au filtrage.
GET /wp-json/wp/v2/posts?_embed=wp:featuredmedia,author&_fields=id,slug,title.rendered,_embedded.wp:featuredmedia,_embedded.authorSur un projet de blog que j’ai livré début 2020, cette combinaison a permis de conserver uniquement l’URL de l’image et le nom d’affichage de l’auteur, sans les tailles d’image inutilisées ni la description complète du profil auteur.
Mesurer le gain réel
Sur ce même projet, j’ai comparé le poids d’une réponse de liste de dix articles avant et après filtrage :
| Configuration | Poids de la réponse |
|---|---|
| Route par défaut, sans filtrage | ≈ 38 Ko |
Avec _fields ciblé (6 champs) | ≈ 11 Ko |
Avec _fields + _embed filtré | ≈ 13 Ko |
Soit une réduction d’environ 71 % du poids transféré, mesurée sur ce cas précis. Le gain varie évidemment selon le contenu réel des articles (un article avec un contenu très long pèse plus lourd par défaut, donc le filtrage paie davantage), mais l’ordre de grandeur se retrouve sur la plupart des sites que j’ai audités.
Ce que _fields ne fait pas
- Il ne réduit pas le nombre de requêtes SQL exécutées par le contrôleur REST : WordPress construit d’abord la réponse complète, puis la filtre.
- Il n’accélère donc pas significativement le temps de réponse serveur, seulement le temps de transfert réseau et le temps de traitement JSON côté client.
- Il ne fonctionne pas sur les routes personnalisées, sauf si vous appelez vous-même
rest_filter_response_fieldsou implémentez un filtrage équivalent dans votre callback.
Sur un projet headless, j’active systématiquement
_fieldsdès la première requête de liste, avant même de me préoccuper de la mise en cache : c’est le gain le plus simple à obtenir, pour un coût d’implémentation proche de zéro.
En résumé
Le paramètre _fields est l’un des leviers les plus rentables pour alléger les réponses de l’API REST WordPress sur un front découplé. Il se combine sans difficulté avec _embed, à condition de penser à inclure les clés imbriquées dans la liste des champs demandés. Sur une liste de vignettes classique, il n’est pas rare de diviser par trois le poids de la réponse, sans aucune modification côté serveur.
