Die Versionierung von APIs ist das Kennzeichnen von Ständen einer Schnittstelle. Sie erlaubt es, die Schnittstelle weiterzuentwickeln, ohne dass bestehende Anbindungen von einem Tag auf den anderen nicht mehr funktionieren.
- Versionierung von APIs
Die Kennzeichnung und parallele Bereitstellung verschiedener Stände einer Schnittstelle, damit Aufrufer selbst bestimmen, wann sie wechseln.
Beispiel: „Dank der Versionierung von APIs läuft unsere Anbindung noch auf v1, während der Anbieter v2 schon freigegeben hat.“Auch: API-Versionierung.
Verwandt: Versionierung, die Verwaltung von Ständen allgemein, etwa im Code.
Wege der Versionierung von APIs
Am verbreitetsten ist die Version in der Adresse, etwa /v1/kunden und /v2/kunden. Sie ist auf einen Blick sichtbar und leicht zu cachen.
Andere Schnittstellen erwarten die Version in einem Header oder über ein Datum. Stripe etwa legt die Version jedes Kontos über ein Datum fest, und Änderungen greifen erst, wenn der Kunde sie ausdrücklich übernimmt.
Was eine neue Version braucht
Nur Änderungen, die bestehende Aufrufer brechen würden: ein entferntes Feld, ein umbenannter Endpunkt, ein geändertes Format. Ein neues optionales Feld ist dagegen kein Bruch und kommt ohne neue Version aus.
Die Regeln dafür sind dieselben wie bei der semantischen Versionierung von Software: Nur ein Bruch erhöht die erste Zahl.
Wie alte Versionen abgeschaltet werden
Mit Vorlauf. Gute Anbieter kündigen das Ende einer Version Monate vorher an, oft zusätzlich über einen Header in jeder Antwort, und dokumentieren die Änderungen in einem Changelog.
Für Website-Betreiber heißt das: Mails von Anbietern angebundener Dienste nicht ungelesen archivieren. Eine abgekündigte Schnittstelle ist einer der häufigsten Gründe, warum ein Formular oder ein Import plötzlich nicht mehr läuft.