Was bedeutet API-Versionierung?
Ändert sich eine Schnittstelle wesentlich, können ältere und neuere Vertragsstände zeitweise nebeneinander bestehen. Die Version lässt sich beispielsweise in der Adresse oder in zusätzlichen Anfrageangaben kennzeichnen.
Wichtiger als die Schreibweise ist die klare Zusage, welche Änderungen bestehende Anwendungen vertragen müssen. Eine reine Verbesserung im Hintergrund benötigt nicht automatisch eine neue öffentliche Version.
So sieht das in der Praxis aus
Beispiel: Eine alte Auftrags-API bleibt während der Umstellung auf ein neues Pflichtfeld verfügbar.
Häufige Fragen
Erfordert jedes zusätzliche Datenfeld eine neue Version?
Nicht zwingend. Wenn bestehende Nutzer unbekannte Felder zulassen, kann es kompatibel sein. Strenge Prüfregeln oder geänderte Bedeutungen können trotzdem Anpassungen erfordern.
Wie lange sollten zwei Versionen parallel laufen?
Dafür gibt es keine allgemeine Frist. Entscheidend sind zugesagte Unterstützung, Umstellungsaufwand und tatsächliche Nutzung. Das Abschaltdatum sollte früh bekannt sein.
Gehört die Versionsnummer zwingend in die Adresse?
Nein. Auch Anfrage-Header oder Medientypen sind möglich. Das gewählte Verfahren muss dokumentiert sein und von den verwendeten Werkzeugen unterstützt werden.