Une extension de gestion de stocks pour magasins de bricolage expose depuis 2016 une API REST sous le namespace stocks/v1, consommée par une douzaine d’intégrations tierces développées par différents clients au fil des années : applications mobiles internes, tableaux de bord Excel connectés via macro, scripts de synchronisation vers des ERP variés. L’équipe qui maintient l’extension souhaite désormais changer la structure de la réponse pour un point de terminaison central, en renommant un champ ambigu et en modifiant le format d’une date, un changement jugé nécessaire mais incompatible avec les intégrations existantes qui dépendent de l’ancienne structure.
Casser purement et simplement ce contrat aurait cassé toutes les intégrations tierces du jour au lendemain, sans préavis, pour des clients qui n’ont pas forcément les ressources techniques pour réagir dans l’urgence. La solution retenue s’appuie sur une propriété que l’API REST de WordPress porte nativement depuis sa conception : le namespace inclut par convention un numéro de version.
Le namespace comme unité de versionnement
Chaque appel à register_rest_route() prend en premier argument un namespace, généralement de la forme mon-domaine/v1. Rien n’empêche de déclarer un second namespace, mon-domaine/v2, pour un ensemble de routes au contrat différent, tout en conservant le premier namespace parfaitement fonctionnel pour les intégrations qui n’ont pas encore migré :
