Versionnage et obsolescence de l'API
VaultPAM utilise un versionnage majeur par chemin (path-major) pour ses API HTTP publiques.
Modèle de versionnage
- Les changements additifs restent dans la version majeure actuelle.
- Les changements incompatibles nécessitent un nouveau chemin majeur tel que
/api/v2/. - La version majeure publique actuelle est
v1.
Changements incompatibles
Un changement est incompatible lorsqu'il supprime ou restreint un contrat client existant, par exemple :
- la suppression d'un point de terminaison ou d'une méthode HTTP,
- le passage d'un champ de requête optionnel à obligatoire,
- la suppression d'un champ de réponse utilisé par des clients existants,
- la modification du type d'un champ d'une manière incompatible,
- le durcissement des règles d'authentification ou d'accès d'une manière qui casse les clients documentés.
Obsolescence et retrait
- Les opérations obsolètes sont signalées dans le contrat de l'API.
- Les notes de version incluent des recommandations de migration dans la même version que celle qui introduit l'obsolescence.
- Un comportement obsolète reste disponible pendant au moins deux versions de production étiquetées avant sa suppression.
- Les dates de retrait sont annoncées à l'avance afin que les clients puissent planifier leur migration.
Accompagnement à la migration
Lorsqu'une API évolue, le chemin de remplacement doit être documenté à côté de la notice d'obsolescence. Les clients ne devraient pas avoir à deviner vers quel point de terminaison ou quelle structure de charge utile migrer ensuite.
Besoin d'aide ?
Consultez la référence API en direct pour connaître les détails actuels des points de terminaison, et les notes de version pour les changements qui affectent les mises à niveau.