Ce document décrit la politique de versionning et de dépréciation des API afin d'assurer une cohérence, une évolutivité et une fiabilité à long terme tout en permettant une transition en douceur pour nos clients. Elle est sujette à révision pour s'adapter aux nouvelles exigences et aux meilleures pratiques de l'industrie.
1 - Numérotation des versions
Nous utilisons le schéma de versionning sémantique standard pour toutes les API, défini par :
- Majeure (MAJOR): Changements incompatibles avec les versions précédentes (breaking changes)
- Mineure (MINOR) : Nouvelles fonctionnalités rétro-compatibles avec les versions précédentes
- Corrective (PATCH) : Corrections de bugs ou failles de sécurité rétro-compatibles
Exemple : 1.2.1
2 - Maintenance des versions
Dés lors qu'une nouvelle version est publiée, les versions précédentes sont dites "dépréciées".
Elles restent fonctionnelles mais n'évoluent plus, et sont maintenues pendant une période limitée :
- Versions majeures : Supportées pendant 2 ans après la publication d'une nouvelle version majeure.
- Versions mineures : Supportées tant que la version majeure associée est supportée.
- Versions correctives : Supportées tant que la version majeure associée est supportée.
Au-delà de la période de support, les versions dépréciées sont susceptibles d'être définitivement retirées. Elles renvoient alors un code d'erreur HTTP spécifique indiquant leur indisponibilité.
3 - Communication & Documentation
Toute mise à disposition d'une nouvelle version d'API majeure est communiquée dans les releases notes.
Un rappel est effectué 6 mois avant la fin de période de support des versions dépréciés pour encourager les derniers clients à migrer.
Les changements entre les versions ainsi que instructions de migration sont décrites dans la documentation API disponible ici