Si chaque extension pouvait déclarer n’importe quelle route à la racine de l’API, deux extensions distinctes risqueraient d’enregistrer la même URL et de s’écraser l’une l’autre. Ce préfixe agit comme une signature qui isole les routes de chaque extension dans son propre compartiment.
Convention de nommage
Le cœur de WordPress réserve l’espace wp/v2 pour ses propres ressources ; une extension doit choisir un espace distinct, généralement composé de son nom suivi d’un numéro de version :
add_action( 'rest_api_init', function () {
register_rest_route( 'mon-extension/v1', '/statistiques', array(
'methods' => 'GET',
'callback' => 'obtenir_statistiques',
) );
} );L’URL finale obtenue est alors /wp-json/mon-extension/v1/statistiques, aisément identifiable comme provenant de cette extension précise.
Bon à savoir
- Le numéro de version dans l’espace de noms (
v1,v2) permet de faire évoluer une API sans casser les intégrations existantes : on ajoute un nouvel espace plutôt que de modifier le format d’une route déjà publiée. - La liste de tous les espaces de noms disponibles sur un site est visible à la racine
/wp-json/, ce qui aide au diagnostic quand une route semble introuvable. - Deux extensions différentes qui choisiraient exactement le même espace de noms verraient leurs routes se mélanger dans les mêmes réponses de découverte, une raison de plus pour lier ce préfixe au nom réel de l’extension.
- Faire évoluer une route de façon incompatible sans changer le numéro de version de son espace de noms risque de casser silencieusement toute application tierce déjà connectée à l’ancien format de réponse.