Namespace REST

Définition : Le namespace REST est le préfixe logique des routes d’un plugin ou d’une application WordPress. Il évite les collisions entre extensions et identifie généralement une version de leur contrat API.

Comprendre et utiliser

À quoi sert cette notion ?

Il permet à plusieurs plugins d’exposer des chemins distincts sans se remplacer. Un nom d’éditeur ou de produit suivi d’une version facilite aussi l’évolution des clients.

Fonctionnement technique

Dans register_rest_route(), le namespace est distinct du chemin. Le serveur assemble ces éléments pour identifier l’endpoint final, par exemple atoolpha/v1 associé à /statut.

Dans quel contexte l’utiliser ?

Une extension ATOOLPHA publie atoolpha/v1 pour son contrat stable. Une future évolution incompatible pourra être exposée sous atoolpha/v2, sans casser immédiatement les intégrations précédentes.

Étude de cas : application professionnelle

Pour une API ATOOLPHA exposée à plusieurs outils, sélectionner le namespace avant la première intégration. Le segment v1 doit correspondre à un engagement de compatibilité, et non à un numéro de version du plugin WordPress. Quand une réponse change de structure de manière incompatible, envisager un nouveau namespace et une période de transition. Un client ne doit jamais supposer qu’un endpoint absent peut être remplacé par une route d’un autre plugin. Conserver un contrat documenté par version limite les interventions de dépannage lors de futures évolutions.

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
// Dans un plugin, au chargement de l’API REST.
add_action( 'rest_api_init', function () {
    register_rest_route( 'atoolpha/v1', '/statut', array(
        'methods' => 'GET',
        'callback' => fn() => array( 'statut' => 'ok' ),
        'permission_callback' => '__return_true',
    ) );
} );

Décryptage du code et résultat attendu

Le préfixe atoolpha/v1 sépare cette route des routes wp/v2 du Core. Le callback public retourne seulement une donnée fictive non sensible.

Exercice guidé pour vérifier la notion

Dans un environnement local, enregistrer la route, consulter /wp-json/atoolpha/v1/statut et vérifier la présence de son namespace dans l’index.

Précautions et limites

La présence de v1 ne garantit pas une compatibilité future : les changements incompatibles demandent une vraie stratégie de versionnement et des tests clients.

À ne pas confondre

Le namespace n’est pas une catégorie WordPress et ne remplace ni l’authentification ni les capacités utilisateur.

Diagnostic avancé

Si la route manque, inspecter le hook rest_api_init et vérifier que le nom du namespace ne comporte pas une barre oblique superflue.

Choix d’architecture et déploiement

Choisir un namespace stable lié au fournisseur, non au domaine temporaire. Maintenir un changelog si des applications externes consomment ces données.