Zum Inhalt springen

Versionierung von APIs

oder auch API-Versionierung

Männliche Person, frontal, schaut in die Kamera; trägt kariertes Hemd über dunkelfarbigem T‑Shirt; heller Innenraum mit unscharfem Monitor oder Poster links und Fenster rechts.

von Richard Albrecht am 08.11.2026

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.

Siehe auch:

Versionierung

Das Festhalten und Benennen von Ständen, sodass sich jeder frühere Stand wiederfinden lässt.

#Deployment & Versionierung

Semantische Versionierung (SemVer)

Die Regel, Versionsnummern als Hauptfassung, Nebenfassung und Korrektur zu lesen.

#Deployment & Versionierung

REST-API

Eine Schnittstelle, die Daten als Ressourcen unter festen Adressen anbietet und über HTTP-Methoden bearbeiten lässt.

#Programmiersprachen

Changelog

Die geführte Liste aller Änderungen einer Software, nach Fassungen geordnet.

#Deployment & Versionierung

Header (API)

Eine Zusatzangabe in einer Anfrage oder Antwort einer Schnittstelle, etwa zu Format oder Anmeldung.

#Programmiersprachen

Endpunkt (API)

Eine bestimmte Adresse einer Schnittstelle, unter der eine Funktion oder Ressource erreichbar ist.

#Programmiersprachen