v.Api – Versionierung
Inhalt
Versionierungskonzept
Mit der Versionsnummer der v.Api kannst du sofort erkennen, welche Version der Api gerade bei dir im Einsatz ist und welche Funktionen aktuell unterstützt werden. Zusätzlich stellen wir über die Versionierung sicher, dass bestimmte Versionen der v.Api untereinander abwärtskompatibel sind.
Die Versionsnummer der v.Api besteht grundsätzlich aus drei Ziffern, zum Beispiel: v.Api – Version 1.0.10
Jede Ziffer steht für einen Versionszwei der Api und hat unterschiedliche Bedeutungen
Major-Version (Erste Ziffer – 1.x.x)
Die Major-Versionsnummer wird nur bei grundlegenden Änderungen an der v.Api hochgesetzt (z.B. kompletter Technologiewechsel). Versionen mit unterschiedlichen Major-Versionsnummer sind nicht untereinander kompatibel. Falls mehrere Major-Versionen parallel eingesetzt werden sollen, müssen diese an einem eigenen Endpoint bereitgestellt werden.
Major-Version
- Vollständig eigenständige Versionen
- Keine Abwärtskompatibilität
- Neuer Endpoint erforderlich
- Advertisment über die Api
Minor-Version (Zweite Ziffer – x.0.x)
Die Minor-Versionsnummer wird bei breaking changes geändert, d.h. bei Änderungen, die das Verhalten der Api ändern und damit an sich nicht mehr abwärtskompatibel sind. Darunter fallen zum Beispiel veränderte Datenstrukturen oder Funktionen die ein anderes Ergebniss liefern. Keine breaking changes sind Bugfixes und das reine hinzufügen von Daten in Datenstrukturen.
Umgekehrt bedeutet das, dass bei der selben Minor-Version die Api sich bei schon vorhanden Funktion immer gleich verhält. Mehrere Minor-Versionen können parallel auf dem selben Endpoint installiert werden. Über den X-Version Header kannst du bei jeder Anfrage an die Api spezifizieren, welche Version du gerade aufrufen möchtest.
Minor-Version
- Geänderte Funktionen oder Breaking Changes
- Abwärtskompatibilität innerhalb einer Version gewährleistet
- Können über den selben Endpoint angesprochen werden (via X-Version)
- Advertisment über die Api
Release-Version (Dritte Ziffer – x.x.10)
Die Release oder Patch-Version kennzeichnet die laufende Versionsnummmer der aktuellen Major/Minor Version der v.Api. Sobald neue Features und Funktionen zur Api hinzukommen setzen wir die Release-Versionsnummer hoch. Die genauen Änderungen kannst du der Versionshistory der Api entnehmen. Release-Versionen in der selben Minor-Version sind natürlich weiter abwärtskompatibel.
Release-Version
- Neue Funktionen und Features, Fehlerbehebungen
- Abwärtskompatibilität innerhalb der Major-Version
- Kein Advertisment über die Api
Advertisment der Api-Version und X-Version
Wahl der Minor-Version über X-Version
Die verschiedenen Minor-Versionen der v.Api werden bei deinem Endpoint gleichzeitig zur Verfügung gestellt. Über den X-Version Header kannst du bei jeder abfrage spezifizieren, welche Minor-Version der Api du gerade ansprechen möchtest. Falls du keine Version angibst wird immer die neuste (d.h. höchste Versionsnummer ausgeliefert)
Abfrage der Versione über X-Version. Je nach angefragter Version liefert die Api entweder Version 1.1 oder 1.0 aus
Advertisment der Api-Versionen
Die v.Api gibt bei jeder Antwort von selbst einen api-supported-versions Header im Respone zurück. Über diesen Header kannst du einsehen, welche Minor-Versionen für die aktuelle Funktion zur Verfügung stehen.
Der Header api-supported-versions zeigt dir, das die Funktion in Version 1.0 und 1.1 verfügbar ist
Abfragen der aktuellen Version
Die aktuell von dir genutzte Version der Api kannst du jederzeit mit GET /api/Version/Current abfragen
Abfrage der aktuellen Version über api/version/current