Versioning e deprecazione dell'API
VaultPAM utilizza il path-major versioning per le API HTTP pubbliche.
Modello di versioning
- I cambiamenti additivi rimangono nella versione principale corrente.
- I breaking changes richiedono un nuovo path principale come
/api/v2/. - La versione principale pubblica corrente è
v1.
Breaking changes
Un cambiamento è considerato breaking quando rimuove o riduce un contratto client esistente, come ad esempio:
- la rimozione di un endpoint o di un metodo HTTP,
- la trasformazione di un campo di richiesta opzionale in obbligatorio,
- la rimozione di un campo di risposta utilizzato dai client esistenti,
- il cambio di un tipo di campo in modo incompatibile,
- l'irrigidimento delle regole di autenticazione o accesso in modo da compromettere i client documentati.
Deprecazione e sunset
- Le operazioni deprecate sono contrassegnate nel contratto dell'API.
- Le note di rilascio includono le linee guida per la migrazione nello stesso rilascio che introduce la deprecazione.
- Il comportamento deprecato rimane disponibile per almeno due rilasci di produzione contrassegnati prima della rimozione.
- Le date di sunset vengono annunciate in anticipo in modo che i clienti possano pianificare la loro migrazione.
Supporto per la migrazione
Quando un'API cambia, il percorso sostitutivo deve essere documentato insieme all'avviso di deprecazione. I clienti non dovrebbero dover indovinare quale endpoint o forma di payload utilizzare successivamente.
Hai bisogno di aiuto?
Utilizza il riferimento API live per i dettagli degli endpoint correnti e le note di rilascio per i cambiamenti che interessano gli aggiornamenti.