Pourquoi tant d’équipes tentent-elles, à un moment ou un autre, d’ajouter une balise <meta name="description"> directement dans la réponse d’un point de terminaison REST de WordPress ? La question mérite d’être posée franchement, parce que la réponse révèle une confusion fréquente entre deux couches très différentes : la donnée et le document.
Sur un site utilisant WordPress en configuration headless partielle, où le contenu est géré côté back-office mais affiché par une application front séparée, cette confusion coûte cher : du temps passé à chercher comment « optimiser » une route JSON qui ne sera jamais lue par un moteur de recherche de cette façon.
Ce que renvoie réellement un endpoint REST
Un appel à /wp-json/wp/v2/posts/42 renvoie un objet JSON structuré : titre, contenu au format HTML échappé, extrait, métadonnées personnalisées éventuellement exposées via register_rest_field(). Rien dans cette réponse ne constitue un document HTML consultable par un navigateur classique, et rien n’y ressemble à une balise <head>.
Googlebot, comme tout robot d’indexation standard, n’exécute pas de logique de rendu sur une réponse dont l’en-tête Content-Type vaut application/json. Il n’y a tout simplement personne, côté moteur de recherche, pour lire un champ meta caché dans cette structure : le concept même de balise meta n’existe que dans le contexte d’un document HTML.
Où se situe la frontière indexable
La frontière se situe exactement à l’endroit où l’application front consomme les données REST et les transforme en document HTML complet. C’est ce document final, servi à l’URL publique du site, qui doit porter la balise title, la meta description, les données structurées et le lien canonique, pas la route JSON qui a fourni la matière première.
Sur le site headless partiel étudié ici, l’architecture se présente ainsi :
Navigateur / Googlebot
│
▼
https://exemple.fr/actualites/mon-article ← page HTML indexable
│ (rendue par l'application front, avec <title> et <meta>)
▼
https://exemple.fr/wp-json/wp/v2/posts/42 ← source de données JSON
│ (jamais appelée directement par un robot)
Ajouter des balises meta dans la réponse REST reviendrait à décorer un plan de construction plutôt que le bâtiment lui-même : le plan reste utile, mais il n’est pas ce que visitent les gens.
Un cas concret d’erreur d’aiguillage
Sur ce site, une équipe avait développé un filtre rest_prepare_post pour injecter un champ seo_meta personnalisé dans chaque réponse d’article, en espérant que cela « améliore le SEO ». Le champ était bien présent dans le JSON, correctement rempli, mais totalement ignoré par l’application front qui ne le consommait pas encore à ce stade du développement.
- Le champ existait côté API, ce qui donnait une fausse impression de travail accompli
- Aucune page rendue ne l’utilisait réellement dans son
<head> - Le résultat concret sur les extraits Google restait celui du gabarit par défaut, non personnalisé
Le correctif n’était pas de modifier la réponse REST, déjà correcte, mais de brancher l’application front sur ce champ pour qu’elle génère effectivement la balise meta correspondante au moment du rendu.
Exposer des données utiles sans confondre les rôles
Il reste tout à fait légitime d’exposer, via register_rest_field(), des champs pensés pour le référencement : un titre optimisé distinct du titre éditorial, une description courte, une image dédiée au partage social. La bonne pratique consiste à les traiter comme des données parmi d’autres, à charge pour la couche de rendu de les transformer en balises au bon endroit.
register_rest_field( 'post', 'seo_title', array(
'get_callback' => function ( $post ) {
return get_post_meta( $post['id'], '_seo_title', true );
},
) );Cette séparation nette entre production de données et production de document facilite aussi la maintenance : on peut changer d’application front, ou même passer d’un rendu côté client à un rendu côté serveur, sans jamais toucher à la structure des données exposées par l’API.
Vérifier ce que Google voit réellement
Le seul test qui compte reste l’outil d’inspection d’URL de Search Console, appliqué à l’URL publique finale, jamais à la route /wp-json/. Si la balise title et la meta description n’apparaissent pas correctement dans le rendu capturé par cet outil, le problème se situe dans la couche de rendu front, pas dans l’API elle-même, qui n’a jamais eu vocation à porter ces informations.
Une réponse JSON n’a pas de tête, au sens HTML du terme. Chercher à lui en donner une revient à résoudre un problème qui n’existe pas, en laissant de côté le vrai chantier : le rendu final vu par le robot.
Pour aller plus loin
Cette distinction entre donnée et document dépasse largement le cas du référencement : elle structure toute architecture headless bien pensée. Tant que cette frontière reste claire dans l’équipe, chaque nouveau champ ajouté à l’API se pose naturellement la bonne question : sert-il à construire un document indexable, ou seulement à transporter une information vers l’application qui, elle, construira ce document ?
