Un champ prix retourné en chaîne de caractères formatée sur une route, en nombre décimal brut sur une deuxième, et en objet structuré avec devise et montant sur une troisième : c’est ce que révèle un audit du schéma REST d’un projet headless en évolution depuis plusieurs années, sans qu’aucune de ces routes ne porte de numéro de version distinct dans son chemin.
Ce genre de situation ne résulte jamais d’une décision unique et consciente. Elle s’accumule progressivement, ajout après ajout, chaque développeur successif reproduisant fidèlement le style qu’il a trouvé en arrivant, ou introduisant sa propre convention faute de documentation de référence à suivre.
Comment cette dérive s’installe
Le point de départ est presque toujours anodin : un premier endpoint personnalisé enregistré sous projet/v1/produits, avec un format de réponse pensé pour les besoins du moment. Six mois plus tard, un deuxième développeur ajoute un champ à cette même route, en conservant le format existant pour ne rien casser côté front déjà en production. Un an après, une nouvelle fonctionnalité nécessite une route différente, conçue par une autre personne, qui reprend certes le préfixe v1 par habitude, mais choisit un format de donnée différent pour un champ conceptuellement identique, sans avoir connaissance du précédent.
Le symptôme le plus visible : la peur de toucher au schéma
Cette accumulation produit un effet paralysant : personne dans l’équipe ne sait plus avec certitude quel front consomme quelle variante du schéma, et toute tentative d’harmonisation devient risquée, faute de documentation permettant d’évaluer l’impact réel d’un changement. Le résultat est une inertie croissante, où il devient plus simple d’ajouter une quatrième variante que de corriger les trois précédentes.
Cartographier avant de corriger
La première étape consiste à établir un inventaire exhaustif des routes personnalisées, avec le format exact de chaque champ retourné, plutôt que de partir directement dans une refonte :
wp eval '
foreach ( rest_get_server()->get_routes() as $route => $handlers ) {
if ( strpos( $route, "/projet/" ) === 0 ) {
echo $route . PHP_EOL;
}
}
'
Cet inventaire, croisé avec une revue du code front qui consomme chaque route, permet d’identifier précisément quelles variantes sont encore utilisées activement et lesquelles ne le sont plus, avant toute décision de correction.
La sortie : un espace de noms versionné correctement
La solution durable consiste à introduire une véritable convention de versionnement dans l’espace de noms des routes, en réservant un numéro de version distinct à chaque changement de format non rétrocompatible :
register_rest_route( 'projet/v2', '/produits', array(
'methods' => 'GET',
'callback' => 'projet_v2_get_produits',
'schema' => 'projet_v2_produit_schema',
) );Les anciennes routes en v1 restent fonctionnelles, sans modification, le temps que les clients existants migrent vers la nouvelle version. Cette coexistence assumée, plutôt que niée, transforme une dérive silencieuse en une évolution maîtrisée et traçable.
Documenter le contrat, pas seulement le code
Un schéma versionné correctement ne suffit pas sans documentation du contrat associé à chaque version. L’argument schema de register_rest_route() permet de déclarer formellement la structure attendue, ce qui alimente automatiquement la découverte du schéma via l’option OPTIONS de la route, consultable par n’importe quel client sans documentation externe.
- Établir un inventaire complet des routes et de leurs formats avant toute tentative d’harmonisation.
- Réserver un nouveau préfixe de version à chaque changement de format non rétrocompatible.
- Déclarer explicitement le schéma de chaque route via l’argument dédié, plutôt que de laisser le format implicite dans le code du callback.
Un schéma qui change sans version associée n’est jamais un problème immédiat : c’est une dette qui s’accumule silencieusement jusqu’au jour où plus personne ne peut la rembourser sans casser quelque chose en production.
En résumé
Trois formats différents pour un même concept ne signalent pas une négligence individuelle, mais l’absence d’une convention de versionnement posée dès le premier endpoint personnalisé. Rattraper cette dérive demande un inventaire rigoureux et une réintroduction progressive du versionnement, mais l’effort reste largement inférieur à celui qu’exigerait une refonte complète menée dans l’urgence, une fois la situation devenue réellement bloquante.
