register_rest_route()

Définition : register_rest_route() enregistre auprès de WordPress une route de l’API REST et ses endpoints. Elle définit les méthodes HTTP, les callbacks, les permissions et les arguments autorisés à entrer.

Comprendre et utiliser

À quoi sert cette notion ?

Elle permet de publier une interface de lecture ou d’écriture contractuelle depuis un plugin sans créer de contrôleur HTTP parallèle au Core.

Fonctionnement technique

La fonction reçoit un namespace, un chemin relatif et les options d’un ou plusieurs endpoints. Elle doit être appelée sur rest_api_init et chaque endpoint doit déclarer un permission_callback adapté.

Dans quel contexte l’utiliser ?

Exposer une liste limitée de ressources publiques ATOOLPHA, avec un nombre maximal d’entrées par réponse.

Étude de cas : application professionnelle

La conception d’une route commence par la définition de sa ressource et de son public. Décrire ensuite les méthodes, les paramètres, leur validation et leurs réponses. La callback devrait se limiter à orchestrer la lecture ou l’action métier et la préparation du résultat. Dans l’exemple public proposé, aucune donnée privée n’est consultée ; c’est ce qui justifie la permission ouverte. Dès qu’une route touche à un dossier privé, remplacer ce contrôle par une permission adaptée. Tester systématiquement les appels non authentifiés et les paramètres invalides.

Exemple technique commenté

Cet extrait est destiné à un fichier PHP chargé par WordPress, idéalement dans un plugin local de test. Il ne doit pas être placé dans l'éditeur de contenu. Avant exécution, vérifier que les objets et variables mentionnés existent dans le contexte et que les permissions nécessaires sont définies.

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'atoolpha/v1', '/ressources', array(
        'methods'  => WP_REST_Server::READABLE,
        'callback' => function () {
            return array( 'ressources' => array() ); // Démo sans données réelles.
        },
        'permission_callback' => '__return_true',
    ) );
} );

Décryptage du code et résultat attendu

La fonction associe GET à une callback qui produit une collection JSON vide. Dans une vraie extension, la collecte de données et les vérifications seraient réalisées dans une couche métier dédiée.

Exercice guidé pour vérifier la notion

Créer la route dans un plugin de test, comparer GET et POST et vérifier les droits affichés via OPTIONS.

Précautions et limites

Une permission_callback absente provoque une notice WordPress ; __return_true n’est approprié que pour une route réellement publique. Ne jamais l’utiliser pour des données privées.