API-Versionierung und Deprecation

VaultPAM verwendet eine pfadbasierte Major-Versionierung für öffentliche HTTP-APIs.

Versionierungsmodell

• Additive Änderungen verbleiben in der aktuellen Major-Version.
• Breaking Changes erfordern einen neuen Major-Pfad wie /api/v2/.
• Die aktuelle öffentliche Major-Version ist v1.

Breaking Changes

Eine Änderung ist ein Breaking Change, wenn sie einen bestehenden Client-Vertrag entfernt oder einschränkt, beispielsweise:

• das Entfernen eines Endpunkts oder einer HTTP-Methode,
• das Erforderlichmachen eines optionalen Anfragefelds,
• das Entfernen eines Antwortfelds, das bestehende Clients verwenden,
• das Ändern eines Feldtyps auf inkompatible Weise,
• das Verschärfen von Authentifizierungs- oder Zugriffsregeln auf eine Weise, die dokumentierte Clients beeinträchtigt.

Deprecation und Sunset

• Veraltete Operationen werden im API-Vertrag gekennzeichnet.
• Release Notes enthalten Migrationshinweise in derselben Version, die die Deprecation einführt.
• Veraltetes Verhalten bleibt vor der Entfernung für mindestens zwei getaggte Produktions-Releases verfügbar.
• Sunset-Termine werden im Voraus angekündigt, damit Kunden ihre Migration planen können.

Migrationsunterstützung

Wenn sich eine API ändert, sollte der Ersatzpfad zusammen mit dem Deprecation-Hinweis dokumentiert werden. Kunden sollten nicht raten müssen, zu welchem Endpunkt oder welcher Payload-Struktur sie als Nächstes wechseln sollen.

Brauchen Sie Hilfe?

Verwenden Sie die Live-API-Referenz für aktuelle Endpunktdetails und die Release Notes für Änderungen, die Upgrades betreffen.