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

> Une application mobile a besoin d'un champ que l'API REST native ne fournit pas. Plutôt que créer un endpoint dédié, le filtre rest_prepare_post permet d'enrichir la réponse existante en quelques lignes.

- Auteur : WordPress Développement
- Publié le : 2024-05-25
- Mis à jour le : 2024-05-25
- Catégorie : Astuces
- URL : https://www.wpmoderne.fr/tips/rest-prepare-post-ajouter-champ-calcule-api-rest/

## L’essentiel

- Le filtre rest_prepare_post enrichit la réponse d'un endpoint déjà existant
- Aucun nouvel endpoint ni route personnalisée n'est nécessaire
- Le champ calculé reste disponible pour toute application consommant l'API

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 );
}
```

> L'essentiel à retenir : Le filtre rest_prepare_post enrichit la réponse d'un endpoint déjà existant ; Aucun nouvel endpoint ni route personnalisée n'est nécessaire ; Le champ calculé reste disponible pour toute application consommant l'API

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.