Retrait de la version 1

Évolution en préparation

Cette page décrit une évolution non livrée. État au 2026-10-11, d'après les conventions de l'API du connecteur (Serveur/docs/conventions-payload-v2.md § 9), son journal d'avancement, son plan de migration et la note sensaas-remote-control/docs/retrait-connecteur-v1.md. Le retrait est prévu au 1er janvier 2027, date que la source dit révisable selon le calendrier de déploiement réel.

En bref

Depuis le 2026-09-26, toutes les routes du connecteur hors /v2 sont déclarées obsolètes et chaque réponse annonce leur fin : retrait prévu au 1er janvier 2027. Elles restent servies d'ici là, pour la compatibilité avec l'ancienne version de la webapp. Côté connecteur, les fonctions qui manquaient en v2 sont livrées ; reste à faire passer tous les serveurs en version 2 et à valider ces fonctions sur un dossier réel.

La date et la règle

Le plan de migration fixait une règle de durée : la version 1 est figée et maintenue six mois après la mise à disposition générale de la version 2, le retrait à l'échéance étant un point de non-retour, annoncé donc assumé.

Le connecteur porte désormais une échéance : décision du responsable de projet, toutes les routes historiques sont obsolètes et leur retrait définitif est prévu au 1er janvier 2027. La date est unique et révisable sans recompiler, par un réglage du fichier appsettings.json du connecteur.

Comment l'obsolescence est annoncée

Documentation : la description OpenAPI de la version 1 annonce la fin de vie, et toutes ses opérations sont marquées obsolètes.
Réponses : toute route historique répond, en succès comme en erreur, avec les en-têtes Deprecation: true et Sunset (RFC 8594) portant la date de retrait.
Exemptées : la documentation et l'outil de test, l'authentification (commune aux deux versions), la sonde de disponibilité et la configuration locale d'EasyConnect.

Pendant la fenêtre, la décision se pilote avec un instrument : le connecteur compte les appels aux routes v1 et sait dire lesquelles sont encore appelées, par la route GET /v2/diagnostics/v1-usage. C'est ce relevé qui dit si l'échéance peut être tenue.

Voir aussi Conventions de l'API - routes historiques.

Comment la version est choisie aujourd'hui

D'après la note de la passerelle, la version d'API est portée par la donnée, pas par le code et pas par la webapp : chaque serveur enregistré porte sa version, la version 1 étant la valeur par défaut. Faire passer un serveur en version 2 est un changement de configuration.

webapp (un seul dialecte)
   └─► passerelle
         ├─► serveur en version 1 : chemins hérités inchangés
         └─► serveur en version 2 : lectures et écritures traduites vers les routes v2

Conséquence : retirer la version 1 n'est pas un chantier côté webapp. C'est une opération de bascule des serveurs, puis la suppression d'une branche de code dans la passerelle. Sur le site du client, passer en version 2 suppose que le connecteur installé soit un connecteur v2 : voir Migrer un connecteur v1 vers la v2.

Les conditions préalables

La note de la passerelle en pose quatre. Trois relèvent du connecteur, qui les a livrées depuis ; toutes attendent encore une validation sur dossier réel.

[ ] Tous les serveurs actifs, dans tous les environnements (développement, préproduction, production, dossiers clients), sont en version 2. Cela se vérifie en base, pas dans le dépôt.
[x] Le connecteur v2 accepte les écritures de documents avec leurs lignes : objets documents par domaine (vente, achat, stock, interne) et leurs lignes depuis le 2026-09-26, lignes liées depuis le 2026-08-25. Validation par l'équipe de la webapp attendue.
[x] Une route v2 existe pour les documents joints et pour la suppression de tiers : médias d'article depuis le 2026-09-26, médias des six objets porteurs depuis le 2026-10-09 (voir Médias) ; suppression d'un client ou d'un fournisseur depuis le 2026-09-26, refusée explicitement si le tiers porte des pièces.
[x] Le faux refus à la création d'un tiers est corrigé côté connecteur (2026-09-26) ; le contournement qui relit après refus peut alors être retiré de la passerelle.

Le piège : "retirer la v1" retire aussi les chemins hérités

L'échéance couvre toutes les routes hors /v2

La note de la passerelle distinguait deux décisions : basculer les serveurs en version 2, et retirer un jour les chemins hérités du connecteur (requêtes, liste des dossiers, tableau de bord, indicateurs, balance, médias, tarifs, cadencier, recherche, lectures par objet), sur lesquels reposent les lectures héritées de la passerelle.

Le connecteur a depuis rangé toutes ces routes parmi les routes obsolètes, avec la même échéance du 1er janvier 2027. Chaque lecture héritée de la passerelle doit donc être servie par une route v2 avant cette date - même mécanisme de traduction, mais un lot de travail supplémentaire.

Ce que coûte le retrait, côté code

Peu de choses, une fois les conditions réunies :

Passerelle : supprimer la branche "version 1" de l'aiguillage, qui devient inconditionnel ; garder le traducteur, qui reste utile comme adaptateur.
Base : supprimer la colonne qui porte la version et le test associé - ou les conserver comme garde-fou, le coût étant nul.
Webapp : rien. Aucune modification dans ses bibliothèques ni dans ses modules.

Ce qui part avec la version 1, côté connecteur

Le plan de migration range le retrait dans sa dernière phase, avec deux conséquences à connaître :

les requêtes SQL libres sont retirées en même temps que les routes v1, d'après le plan ;
la même phase porte le durcissement final : comptes SQL en moindre privilège, audit de sécurité endpoint par endpoint, sauvegarde de la configuration par le portail et mesure de performance avant/après.

Voir Ce qui reste à livrer côté connecteur.

Questions fréquentes

Faut-il migrer la webapp avant de retirer la version 1 ?

Non. La webapp parle un seul dialecte, et la traduction se fait dans la passerelle. Le retrait ne produit aucun changement dans la webapp.

Que se passe-t-il pour un client resté en version 1 à l'échéance ?

Ses appels cesseraient d'être servis. C'est précisément ce que le relevé d'usage des routes v1 sert à éviter : on sait avant l'échéance qui appelle encore quoi.

La date du 1er janvier 2027 peut-elle bouger ?

Oui : la source la dit révisable selon le calendrier de déploiement réel. Elle se règle sans recompiler, et les en-têtes comme la documentation v1 suivent la valeur réglée.

Le mode de connexion directe au connecteur disparaît-il aussi ?

Non. L'authentification est exemptée de l'obsolescence, commune aux deux versions, et la connexion directe reste toujours ouverte à côté de la connexion par la webapp. Voir Sécurité du connecteur.