# rest_ensure_response : toujours renvoyer un objet WP_REST_Response valide

> Un callback d'endpoint REST peut renvoyer un tableau, un objet ou déjà une réponse complète. Une fonction d'enveloppe évite les surprises de type côté client.

- Auteur : WordPress Développement
- Publié le : 2021-09-30
- Mis à jour le : 2021-09-30
- Catégorie : Astuces
- URL : https://www.wpmoderne.fr/tips/rest-ensure-response-renvoyer-wp-rest-response/

## L’essentiel

- Enveloppe automatiquement une valeur brute dans un WP_REST_Response
- Laisse intact un objet déjà conforme, sans double enveloppe
- Simplifie l'écriture de callbacks qui retournent parfois un WP_Error

`register_rest_route()` accepte un callback qui peut, en théorie, retourner à peu près n'importe quoi : un tableau associatif, un objet `stdClass`, un objet `WP_Error`, ou déjà un `WP_REST_Response` correctement construit. Le client qui consomme l'API, lui, attend un format cohérent et prévisible d'un endpoint à l'autre.

`rest_ensure_response()` fait le lien entre ces deux mondes : elle enveloppe systématiquement la valeur retournée dans un objet `WP_REST_Response` valide, sans dupliquer l'enveloppe si elle est déjà présente.

## Ce que fait exactement la fonction

Si la valeur transmise est déjà une instance de `WP_REST_Response`, elle est retournée telle quelle. Si c'est une instance de `WP_Error`, elle est convertie en réponse d'erreur avec le bon code HTTP. Pour toute autre valeur — tableau, chaîne, objet simple — elle est enveloppée dans un nouveau `WP_REST_Response` avec un code 200 par défaut.

> L'essentiel à retenir : Enveloppe automatiquement une valeur brute dans un WP_REST_Response ; Laisse intact un objet déjà conforme, sans double enveloppe ; Simplifie l'écriture de callbacks qui retournent parfois un WP_Error

```
function mon_endpoint_callback( WP_REST_Request $request ) {
    $donnees = array(
        'statut'  => 'ok',
        'valeurs' => array( 1, 2, 3 ),
    );

    return rest_ensure_response( $donnees );
}

register_rest_route( 'mon-plugin/v1', '/donnees', array(
    'methods'  => 'GET',
    'callback' => 'mon_endpoint_callback',
    'permission_callback' => '__return_true',
) );
```

## Pourquoi ne pas construire le WP_REST_Response à la main partout

Construire explicitement un `new WP_REST_Response( $donnees, 200 )` à chaque retour fonctionne, mais ajoute une répétition dans chaque callback, surtout lorsque plusieurs chemins de retour existent dans une même fonction, certains renvoyant une erreur, d'autres un résultat valide.

```
function mon_endpoint_avec_erreur( WP_REST_Request $request ) {
    $id = (int) $request->get_param( 'id' );

    if ( $id <= 0 ) {
        return rest_ensure_response(
            new WP_Error( 'id_invalide', 'Identifiant invalide.', array( 'status' => 400 ) )
        );
    }

    return rest_ensure_response( array( 'id' => $id ) );
}
```

Les deux branches passent par le même appel final, ce qui uniformise le style d'écriture du callback sans condition explicite sur le type de retour.

## Ce que la fonction ne fait pas

- Elle ne valide pas la structure des données transmises : c'est le rôle de l'argument `args` et de ses callbacks de validation dans `register_rest_route()`.
- Elle ne définit pas les en-têtes CORS ni la pagination : ces aspects se règlent séparément sur l'objet `WP_REST_Response` retourné, via ses méthodes `set_headers()` ou `header()`.
- Elle n'est pas obligatoire au sens strict : un endpoint peut fonctionner sans elle si chaque retour est déjà un `WP_REST_Response` bien formé, mais l'omettre revient à réécrire manuellement ce qu'elle fait déjà.

### Un détail utile pour les erreurs multiples

Si un `WP_Error` contient plusieurs erreurs enregistrées via `add_data()`, `rest_ensure_response()` utilise le code de statut associé à la première erreur trouvée. Pour un contrôle plus précis du code HTTP retourné, un appel explicite à `WP_Error::add_data()` avec un tableau contenant la clé `status` reste nécessaire avant l'enveloppe.

> Le réflexe à prendre en écrivant un callback REST : chaque instruction `return` passe par `rest_ensure_response()`, sans exception, y compris pour les branches d'erreur. Cela évite un format de retour incohérent selon le chemin d'exécution emprunté.

## En résumé

`rest_ensure_response()` uniformise le format de retour d'un callback d'endpoint REST, sans imposer de restructurer le code existant. Elle prend en charge aussi bien les valeurs simples que les objets `WP_Error`, et évite les conditions manuelles répétées à chaque point de sortie d'une fonction de callback.