register_rest_field : exposer la disponibilité en temps réel d’une chambre

Une réponse REST standard décrit ce qu’une chambre est, jamais ce qu’elle vaut à l’instant présent. C’est le constat qu’a fait un hôtel indépendant en connectant une application de gestion de planning tierce à son site WordPress : la disponibilité réelle de chaque chambre, une donnée calculée à partir des réservations en cours, restait absente par nature de la réponse REST par défaut d’un type de contenu chambre.

La fonction register_rest_field(), disponible depuis WordPress 4.7, permet précisément d’ajouter un champ à la réponse REST existante sans réécrire tout un contrôleur personnalisé. C’est l’outil qu’il fallait pour exposer cette disponibilité calculée sans dupliquer la logique déjà utilisée côté administration.

Déclarer le champ calculé sur le type de contenu chambre

L’enregistrement se fait via une fonction de rappel de lecture, exécutée à chaque requête, qui calcule la disponibilité en interrogeant les réservations liées à la chambre concernée pour la date du jour.

add_action( 'rest_api_init', function () {
    register_rest_field( 'chambre', 'disponibilite_du_jour', array(
        'get_callback'    => 'ch_calculer_disponibilite_chambre',
        'schema'          => array(
            'description' => 'Disponibilité de la chambre pour la date du jour',
            'type'        => 'boolean',
            'context'     => array( 'view' ),
        ),
    ) );
} );

function ch_calculer_disponibilite_chambre( $objet_chambre ) {
    $reservations = new WP_Query( array(
        'post_type'   => 'reservation',
        'post_status' => 'publish',
        'meta_query'  => array(
            array( 'key' => 'chambre_id', 'value' => $objet_chambre['id'] ),
            array( 'key' => 'date_arrivee', 'value' => current_time( 'Y-m-d' ), 'compare' => '<=' ),
            array( 'key' => 'date_depart', 'value' => current_time( 'Y-m-d' ), 'compare' => '>' ),
        ),
        'posts_per_page' => 1,
        'fields'         => 'ids',
    ) );

    return ! $reservations->have_posts();
}

Vérifier le résultat sur un point d’accès existant

Une fois le champ enregistré, il apparaît automatiquement dans la réponse du point d’accès standard des chambres, sans modification de l’URL ni du format général de la réponse, ce qui évite toute rupture pour les intégrations déjà en place.

GET /wp-json/wp/v2/chambre/58

{
  "id": 58,
  "title": { "rendered": "Chambre Deluxe vue mer" },
  "disponibilite_du_jour": true
}

L’application tierce de gestion de planning n’a eu besoin d’aucune adaptation particulière côté serveur : elle consomme simplement ce nouveau champ au même titre que les champs natifs déjà exposés, ce qui a limité le développement à la seule partie WordPress du projet.

Documenter le champ avec un schéma explicite

Le paramètre schema mérite une attention particulière : il ne se contente pas de documenter le champ pour un humain qui consulterait la documentation générée automatiquement de l’API, il influence aussi le comportement de certains clients REST capables d’interpréter ce schéma pour valider les données reçues.

• Le type boolean plutôt qu’une chaîne de caractères comme "disponible" ou "occupee", plus simple à interpréter côté application tierce.
• Le contexte view uniquement, puisque ce champ calculé n’a pas vocation à être modifiable via une requête d’écriture sur l’API.
• Une description en français, utile pour toute personne qui explorerait l’API via un client de test générique sans connaître le projet en détail.

Pourquoi ne pas stocker directement ce champ en base

Une tentation courante consiste à recalculer la disponibilité une fois par jour via une tâche planifiée, puis à la stocker comme champ personnalisé classique. Cette approche introduit un décalage temporel : une réservation créée en cours de journée ne mettrait pas à jour immédiatement la disponibilité affichée par l’API, ce qui aurait exactement l’effet inverse de ce que l’hôtel recherchait.

// À éviter : un champ stocké devient vite obsolète entre deux recalculs
update_post_meta( $chambre_id, 'disponibilite_du_jour', $disponible );

Le calcul à la volée coûte une requête supplémentaire par appel, un coût largement acceptable au regard du volume de requêtes attendu depuis une application de gestion de planning, généralement interrogée à intervalles espacés plutôt qu’en continu.

Un champ d’API calculé à la demande reste toujours exact ; un champ stocké et recalculé périodiquement finit toujours par mentir entre deux mises à jour.

En résumé

register_rest_field() a permis d’exposer une information dynamique sans toucher au contrôleur REST natif des chambres, ni dupliquer la logique de calcul déjà présente côté administration. Ce projet ne traite volontairement pas la synchronisation avec un canal de réservation externe, un sujet plus large qui suppose une gestion bidirectionnelle des disponibilités entre plusieurs systèmes.