« Avant d’exposer une taxonomie personnalisée en headless : la checklist à suivre »

Une taxonomie personnalisée mal préparée avant son exposition en REST fuit souvent plus d’informations que prévu : des comptages d’articles liés à des statuts internes, des descriptions rédigées pour l’équipe éditoriale plutôt que pour le public, ou des identifiants numériques instables que le front ne devrait jamais afficher tels quels. Cette liste passe en revue les points à vérifier avant d’activer show_in_rest sur une taxonomie déjà utilisée en production.

Elle complète, sans le répéter, tout ce qui concerne les types de contenus personnalisés eux-mêmes : ici, il s’agit uniquement des termes de taxonomie — catégories personnalisées, étiquettes maison, classifications propres à un projet — et de ce qu’ils exposent une fois ouverts à un front découplé.

Les huit points à vérifier

1. Déclaration explicite du support REST. Vérifiez que show_in_rest vaut true dans register_taxonomy(), et que rest_base porte un nom cohérent avec le reste de l’API plutôt que le nom technique interne de la taxonomie.
2. Comptage d’articles associés. Le champ count retourné par /wp/v2/<taxonomie> inclut par défaut tous les statuts visibles par l’utilisateur courant. Pour un visiteur anonyme, seuls les articles publiés sont comptés, mais un jeton d’authentification actif changerait ce total : à tester avec et sans authentification.
3. Description destinée à l’admin, pas au public. Le champ description d’un terme est souvent rempli par l’équipe éditoriale à des fins internes (« à fusionner avec la catégorie voisine », par exemple). Avant ouverture, relisez chaque description ou masquez le champ via register_rest_field() avec un contrôle d’accès.
4. Slugs figés avant le lancement du front. Un slug de terme modifié après coup casse les URL générées côté front si celui-ci les construit à partir du slug plutôt que de l’identifiant. Verrouillez les slugs avant l’ouverture publique de l’API.
5. Termes vides ou orphelins. Une taxonomie qui contient des termes sans article associé (count à zéro) alourdit inutilement les réponses de liste ; un nettoyage préalable via wp term list <taxonomie> --fields=term_id,count en WP-CLI aide à les repérer.
6. Hiérarchie exposée correctement. Pour une taxonomie hiérarchique, le champ parent doit être vérifié : un identifiant de parent qui pointe vers un terme lui-même non publié côté front créerait une incohérence d’affichage.
7. Permissions d’écriture. Par défaut, la création et la modification de termes via REST nécessitent la capacité manage_categories ou l’équivalent défini par register_taxonomy(). Vérifiez qu’aucun rôle non prévu ne peut écrire sur cette route.
8. Cache et invalidation. Si le front met en cache la liste des termes, prévoyez un webhook ou une invalidation programmée : une taxonomie évolue rarement vite, mais un oubli de synchronisation dure alors plus longtemps qu’un oubli sur les articles.

Le piège du comptage caché

Le point le plus souvent négligé reste le comptage d’articles. Un client a un jour signalé qu’un total de « produits en rupture » apparaissait dans une liste de catégories censée n’afficher que des produits disponibles au public. En creusant, le comptage count de la taxonomie product_cat remontait tous les statuts de commande, y compris les brouillons de produits en préparation, car aucun filtre supplémentaire n’avait été appliqué sur la requête REST sous-jacente.

La correction passe généralement par un filtre dédié sur la requête des termes :

add_filter( 'rest_product_cat_query', function( $args, $request ) {
    $args['hide_empty'] = true;
    return $args;
}, 10, 2 );

Masquer un champ sans casser le schéma

Pour retirer un champ sensible d’une réponse de taxonomie sans provoquer d’erreur côté front qui l’attendrait toujours dans le schéma, la meilleure pratique consiste à le vider plutôt qu’à le supprimer :

add_filter( 'rest_prepare_taxonomy_term', function( $response ) {
    $response->data['description'] = '';
    return $response;
} );

Le champ reste présent dans le schéma déclaré, mais sa valeur ne fuite plus d’information interne.

Documenter la checklist pour l’équipe

Une checklist n’a de valeur que si elle est appliquée systématiquement, y compris des mois après le lancement du front, lorsqu’une nouvelle taxonomie est ajoutée au projet. Conserver ces huit points dans un fichier partagé avec l’équipe, et les repasser en revue à chaque nouvelle taxonomie plutôt qu’une seule fois au démarrage du projet, évite que les mêmes fuites de champs internes ne réapparaissent sur un projet qui a grandi.

Notre verdict

Une taxonomie personnalisée n’est jamais « juste des catégories » du point de vue d’une API REST : chaque terme transporte un comptage, une description et une hiérarchie qui peuvent révéler des détails jamais pensés pour un public externe. Passer ces huit vérifications avant chaque ouverture évite la majorité des incidents constatés sur des projets headless déjà en production.