Aller au contenu principal

Versioning API

Statut​

Document de cadrage architecture — version initiale.

État actuel​

L'API visible expose une version v1 via les routes /api/v1.

Les modules chargent leurs routes avec le préfixe api/v1, et le health-check est disponible sous /api/v1/health.

Objectif​

Le versioning API doit permettre de faire évoluer l'écosystème sans casser les applications connectées.

Il doit protéger :

  • DMV public ;
  • backoffice ;
  • PlayLoop ;
  • AssoSuite ;
  • Mairie ;
  • futures apps ;
  • intégrations externes éventuelles.

Principes​

  • La version majeure est dans l'URL : /api/v1.
  • Les changements compatibles restent dans la même version.
  • Les changements cassants nécessitent une nouvelle version ou une stratégie de transition.
  • Les réponses doivent rester stables pour les clients existants.
  • Les dépréciations doivent être documentées.

Changements compatibles​

Exemples :

  • ajout d'un champ optionnel ;
  • ajout d'un endpoint ;
  • amélioration de performance ;
  • ajout d'un filtre optionnel ;
  • correction de bug sans changer le contrat.

Changements cassants​

Exemples :

  • suppression d'un champ ;
  • changement de type ;
  • modification de sémantique ;
  • changement de pagination ;
  • renommage d'endpoint ;
  • changement de règle d'autorisation sans migration prévue.

Documentation cible​

Chaque endpoint critique devrait documenter :

  • méthode ;
  • URL ;
  • source applicative attendue ;
  • auth requise ;
  • permissions ;
  • paramètres ;
  • réponse ;
  • erreurs ;
  • version ;
  • statut de dépréciation.

Risques et points à clarifier​

  • Absence de documentation OpenAPI confirmée.
  • Contrats inter-apps à formaliser.
  • Politique de dépréciation à définir.
  • Gestion des frontends pendant migration d'API.
  • Compatibilité des accès Supabase historiques avec la stratégie API.