rest_prepare_post : ajouter un champ calculé à l’API REST sans nouvel endpoint

La documentation officielle de l’API REST de WordPress précise que chaque type de contenu déclenche un filtre dynamique nommé rest_prepare_{$post_type} juste avant l’envoi de la réponse, permettant de modifier ou d’enrichir les données transmises. Pour le type post, ce filtre se nomme rest_prepare_post, et il constitue la voie la plus directe pour ajouter un champ calculé sans construire un nouvel endpoint entier.

Une application mobile qui consomme l’API REST pour afficher la liste des articles a par exemple besoin d’un temps de lecture estimé, calculé à la volée depuis le nombre de mots du contenu. Ce champ n’existe pas nativement dans la réponse, et créer une route personnalisée uniquement pour l’exposer serait disproportionné par rapport au besoin réel.

Étape 1 : déclarer le champ dans le schéma REST

Avant de remplir une valeur, il faut déclarer le champ pour qu’il apparaisse dans le schéma de l’API et reste documenté pour les consommateurs futurs, via register_rest_field() :

add_action( 'rest_api_init', 'wpm_declarer_champ_temps_lecture' );

function wpm_declarer_champ_temps_lecture() {
    register_rest_field( 'post', 'temps_lecture_estime', array(
        'get_callback' => 'wpm_calculer_temps_lecture',
        'schema'       => array(
            'description' => 'Temps de lecture estimé en minutes',
            'type'        => 'integer',
            'context'     => array( 'view' ),
        ),
    ) );
}

Étape 2 : écrire la fonction de calcul

function wpm_calculer_temps_lecture( $post_data ) {
    $contenu    = get_post_field( 'post_content', $post_data['id'] );
    $nb_mots    = str_word_count( wp_strip_all_tags( $contenu ) );
    $mots_minute = 200;

    return (int) ceil( $nb_mots / $mots_minute );
}

Cette fonction s’appuie sur wp_strip_all_tags() pour ne compter que le texte réel, sans que les balises HTML du contenu ne faussent le décompte de mots, puis divise ce total par une moyenne de lecture de 200 mots par minute, une estimation courante pour du contenu en français.

Étape 3 : vérifier le résultat

Une requête vers /wp-json/wp/v2/posts fait désormais apparaître le champ temps_lecture_estime directement dans chaque objet de la réponse, sans route supplémentaire à documenter ni à maintenir séparément :

{
    "id": 42,
    "title": { "rendered": "Titre de l'article" },
    "temps_lecture_estime": 4
}

Étape 4 : enrichir davantage avec rest_prepare_post

Pour des besoins qui dépassent un simple champ calculé, par exemple ajouter un objet imbriqué construit à partir de plusieurs métadonnées, le filtre rest_prepare_post offre un contrôle plus large que register_rest_field() :

add_filter( 'rest_prepare_post', 'wpm_enrichir_reponse_post', 10, 3 );

function wpm_enrichir_reponse_post( $response, $post, $request ) {
    $response->data['auteur_details'] = array(
        'nom'   => get_the_author_meta( 'display_name', $post->post_author ),
        'photo' => get_avatar_url( $post->post_author ),
    );

    return $response;
}

Choisir entre les deux approches

Pour un champ simple et scalaire, register_rest_field() reste préférable car il documente correctement le champ dans le schéma exposé par l’API. Pour des structures plus complexes ou des modifications qui dépendent du contexte de la requête, comme le paramètre $request, le filtre rest_prepare_post devient nécessaire.

Étape 5 : limiter le calcul aux contextes utiles

Un calcul de temps de lecture exécuté sur chaque article d’une réponse contenant cent éléments peut alourdir légèrement le temps de réponse. Une vérification du paramètre context de la requête permet de ne calculer ce champ que lorsque la vue complète est demandée :

• Retourner une valeur nulle par défaut si le contexte de la requête est embed, plus léger.
• Réserver le calcul complet au contexte view, utilisé pour l’affichage détaillé d’un article.
• Mettre en cache la valeur calculée dans une métadonnée si le volume d’articles devient important, pour éviter un recalcul à chaque requête.

Conseil maison : avant de créer un nouvel endpoint personnalisé, vérifiez toujours si un champ calculé ajouté à une réponse existante ne suffit pas. La maintenance d’une route en moins, c’est une surface d’erreur en moins pour toute l’équipe.

En résumé

Enrichir une réponse REST existante avec register_rest_field() ou rest_prepare_post évite bien souvent la lourdeur d’un nouvel endpoint dédié. Ces deux outils cœur suffisent à répondre à l’immense majorité des besoins d’une application consommant l’API, tant que la donnée ajoutée reste calculable depuis les informations déjà accessibles à WordPress.