« Le champ sous_titre est vide » — c’est le message que reçoit régulièrement un développeur front lorsqu’un champ ACF pourtant rempli dans l’administration WordPress n’apparaît tout simplement pas dans la réponse de /wp/v2/posts/42. Le champ existe, une valeur a bien été saisie, et pourtant l’objet JSON renvoyé par l’API ne contient aucune trace de ce champ personnalisé.
Ce symptôme revient si souvent qu’il mérite une méthode de diagnostic dédiée, plutôt qu’un tâtonnement au cas par cas. Voici la démarche à suivre, du plus probable au plus rare.
Symptôme : le champ est vide ou totalement absent
Deux cas distincts se cachent derrière un symptôme qui semble identique :
- Le champ n’apparaît pas du tout dans la clé
acfde la réponse JSON. - La clé
acfexiste, mais le champ précis y est absent alors que d’autres champs du même groupe sont bien présents.
Distinguer ces deux situations oriente immédiatement le diagnostic : la première pointe vers une configuration globale du plugin, la seconde vers un réglage propre au champ concerné.
Diagnostic étape par étape
1. Le plugin ACF to REST API est-il actif, ou la version d’ACF intègre-t-elle ce support ?
Depuis Advanced Custom Fields 5.11, le support REST est intégré nativement au plugin, sans extension supplémentaire, à condition d’avoir été activé. Sur un projet plus ancien qui utilisait le plugin séparé ACF to REST API, vérifiez qu’il n’a pas été désactivé lors d’une mise à jour.
2. La case « Afficher dans l’API REST » est-elle cochée sur le groupe de champs ?
C’est la cause la plus fréquente, et la plus simple à manquer : dans les réglages d’un groupe de champs ACF, l’onglet des paramètres du groupe contient une option show_in_rest. Si elle est désactivée, aucun champ du groupe n’apparaît dans la réponse REST, quel que soit son contenu.
// Vérification programmatique sur un groupe de champs
$groupe = acf_get_field_group( 'group_65f1a2b3c4d5e' );
var_dump( $groupe['show_in_rest'] );
3. Le champ est-il correctement rattaché au type de contenu concerné ?
Une règle de localisation (« Location Rules ») mal configurée sur le groupe de champs peut le limiter à un seul type de contenu ou à une seule catégorie, alors que l’article testé n’y correspond pas. Dans l’administration, un champ absent de l’écran d’édition d’un article donné n’apparaîtra jamais dans sa réponse REST, même si la case REST est cochée globalement.
4. Le type de champ nécessite-t-il un format de sortie spécifique ?
Pour les champs de type relation, image ou galerie, ACF permet de choisir le format retourné (identifiant, objet complet, tableau). Si le format choisi est id mais que le front attend un objet complet avec l’URL de l’image, le champ paraîtra « vide » du point de vue du front alors qu’il contient bel et bien une valeur, simplement sous une autre forme.
Le correctif le plus courant
Dans l’immense majorité des cas rencontrés, activer la case show_in_rest sur le groupe de champs concerné suffit :
add_filter( 'acf/rest_api/field_settings/show_in_rest', '__return_true' );Ce filtre force l’affichage REST pour tous les groupes de champs du site, ce qui convient pour un projet headless où la totalité des champs ACF doit être disponible côté front. Pour un contrôle plus fin, préférez cocher la case groupe par groupe dans l’interface, afin de ne pas exposer par inadvertance un champ interne à l’équipe éditoriale.
Prévenir la récidive
Ce type d’incident revient typiquement après la création d’un nouveau groupe de champs par un membre de l’équipe qui ignore l’existence de la case REST. Deux mesures limitent le risque :
- Ajouter une note dans la documentation interne du projet, rappelant que tout nouveau groupe de champs ACF doit cocher
show_in_restavant d’être considéré comme prêt pour le front. - Écrire un test automatisé simple qui interroge l’API REST pour un article de test et vérifie la présence des clés ACF attendues, exécuté à chaque déploiement.
En résumé
Un champ ACF absent d’une réponse REST relève presque toujours d’un réglage manquant plutôt que d’un bug du plugin : la case d’affichage REST du groupe de champs, les règles de localisation, ou le format de sortie choisi pour un champ de type relation. Suivre ces quatre vérifications dans l’ordre, du plus fréquent au plus rare, permet de résoudre la quasi-totalité des cas sans avoir à explorer le code source du plugin.
