REST-API-Versionierung: Strategien mit URI, Header und Abwärtskompatibilität

Leitfaden zur API-Versionierung: Liste inkompatibler Änderungen, Versionierung per URI und Header, Header Deprecation und Sunset, CI-Prüfung mit OpenAPI und Migrationszeitplan.
Technische Zusammenfassung
Technologie
REST API, OpenAPI, RFC 8594 Sunset, RFC 9745 Deprecation, oasdiff
Thema
Eine veröffentlichte REST-API abwärtskompatibel weiterentwickeln
Niveau
Mittel bis fortgeschritten
Voraussetzungen
  • Erfahrung im REST-API-Design
  • Vertrautheit mit OpenAPI-Dokumenten
In diesem Beitrag7 Abschnitte

Sobald eine API veröffentlicht ist, gehört sie nicht mehr nur Ihnen: Händlerportal, mobile App, ERP-Connector oder die Integration eines Geschäftspartners binden sich an ihr heutiges Verhalten. Die typische Störung in der Praxis beginnt so: Der Name eines Feldes wird als „kleine Korrektur“ geändert, in derselben Nacht stoppt die Bestellübertragung des Geschäftspartners, und bis zum Morgen findet niemand die Ursache. Versionierung ist die Methode, die API weiterzuentwickeln, ohne Konsumenten unangekündigt zu brechen: inkompatible Änderungen erkennen, die richtige Versionierungsmethode wählen und die alte Version nach Zeitplan abschalten.

Das Problem, das Versionierung löst

API-Anbieter und Konsument arbeiten mit unterschiedlichen Zeitplänen. Sie möchten den Namen eines Feldes ändern; das Entwicklungsteam Ihres Geschäftspartners rührt den Code womöglich monatelang nicht an. Versionierung entkoppelt diese beiden Zeitpläne: Neues Verhalten wird in einer neuen Version veröffentlicht, die alte Version läuft eine festgelegte Zeit unverändert weiter, und der Konsument stellt nach eigenem Plan um.

Versionierung ist kein Ziel, sondern das letzte Mittel. Jede neue Hauptversion bedeutet zwei gleichzeitig gepflegte Codepfade, zwei Dokumentationssätze und zwei Test-Suites. Der Wartungsaufwand verdoppelt sich. Deshalb ist das erste Ziel, Änderungen möglichst abwärtskompatibel zu gestalten und eine neue Hauptversion nur zu veröffentlichen, wenn es unvermeidlich ist. Wenn Sie noch zwischen REST und GraphQL wählen, berücksichtigen Sie, dass GraphQL die Schemaentwicklung anders angeht; dieser Vergleich steht im Leitfaden REST oder GraphQL.

Inkompatible und kompatible Änderungen

Eine inkompatible (breaking) Änderung ist eine, die dazu führt, dass ein bestehender, korrekt geschriebener Client ohne jede Anpassung nicht mehr funktioniert. Verwenden Sie die folgende Unterscheidung als Checkliste beim Review von Änderungen.

Änderung Klasse Hinweis
Neues optionales Feld zur Antwort hinzufügen Nicht inkompatibel* Der Client sollte unbekannte Felder ignorieren
Neuen Endpunkt hinzufügen Nicht inkompatibel —
Neuen optionalen Parameter zur Anfrage hinzufügen Nicht inkompatibel Standardverhalten darf sich nicht ändern
Feld löschen oder umbenennen Inkompatibel Erst neues Feld hinzufügen, Entfernung des alten ankündigen
Feldtyp ändern (Zahl → Text) Inkompatibel Streng typisierte Clients können nicht parsen
Optionalen Parameter zur Pflicht machen Inkompatibel —
Neuen Wert zu einem Enum hinzufügen Kommt darauf an Geschlossene switch-Strukturen können brechen
Validierungsregel verschärfen Inkompatibel Eine Anfrage, die gestern durchging, erhält heute 422
Standard-Seitengröße oder Sortierung ändern Inkompatibel Auch Verhaltensänderungen sind inkompatibel

* Dass das Hinzufügen eines neuen Feldes sicher ist, setzt voraus, dass Konsumenten dem Grundsatz „unbekannte Felder ignorieren“ folgen. Schreiben Sie diese Erwartung ausdrücklich in Ihre API-Dokumentation; Clients mit strenger Schemavalidierung können selbst bei einem neuen Feld einen Fehler auslösen. Genau das bricht in der Praxis am häufigsten: Der Anbieter sagt „wir haben ein Feld hinzugefügt, das ist nicht inkompatibel“, und die per Codegenerator erzeugte Klasse des Konsumenten wirft bei dem unbekannten Feld eine Ausnahme. Schreiben Sie auch kompatible Änderungen in die Versionshinweise; der Konsument soll sehen, was sich geändert hat.

Der verbreitete Weg, eine inkompatible Änderung ohne neue Hauptversion umzusetzen, ist der Ansatz Expand and Contract: Das neue Feld wird neben dem alten hinzugefügt, beide Felder werden eine Zeit lang gemeinsam befüllt, das alte Feld wird als veraltet erklärt und entfernt, sobald seine Nutzung auf null gesunken ist. Das ist langsam. Aber es bricht niemanden.

Versionierung per URI, Header und Parameter

Methode Beispiel Vorteil Einschränkung
URI-Pfad /v2/orders Sichtbar, cache- und logfreundlich, leicht zu routen Identität der Ressource vermischt sich mit der Version
Eigener Header Api-Version: 2026-06-01 URI bleibt stabil, geeignet für feine datumsbasierte Versionierung Im Browser und im Log weniger sichtbar
Medientyp Accept: application/vnd.beispiel.v2+json Kompatibel mit HTTP-Content-Negotiation Client- und Werkzeugunterstützung kann schwach sein
Query-Parameter /orders?api-version=2 Einfach, leicht auszuprobieren Verwirrung bei Cache-Schlüsseln und signierten URLs

In den meisten Unternehmens-Web- und Integrationsprojekten ist die Hauptversion im URI-Pfad ein praktischer Standard: Der Geschäftspartner versteht sie sofort, und in Proxy-, WAF- und Log-Schichten ist sie leicht zu unterscheiden. Bei einer Vorfallsanalyse im Zugriffslog in einer Zeile zu sehen, welche Version aufgerufen wurde, spart viel Zeit. Anbieter, die häufig kleine Änderungen veröffentlichen, bevorzugen dagegen eventuell datumsbasierte Header-Versionierung; so erhält etwa die GitHub REST API die Version im Datumsformat über den Header X-GitHub-Api-Version, Stripe über Stripe-Version. Unabhängig von der gewählten Methode gelten drei Regeln:

  • Das Verhalten einer Anfrage ohne Versionsangabe muss dokumentiert sein (älteste unterstützte Version oder Fehler). Der Standard „immer die neueste“ hebt den Zweck der Versionierung auf; am Tag der Veröffentlichung einer neuen Version bricht jeder, der keine Version angibt.
  • Für Konsumenten sollten nur Hauptversionen (inkompatible Änderungen) sichtbar sein; Neben- und Patch-Versionen bleiben in den Versionshinweisen.
  • Auch Ereignisse, die Sie senden, etwa Webhook-Bodys, sollten versioniert sein. Ein Feld für die Schemaversion im Ereignis-Body ermöglicht dem Empfänger ein sicheres Parsen; zum Design der Empfängerseite lesen Sie den Leitfaden zum Design von Webhook-Empfängern.

Abkündigung: Header Deprecation und Sunset

Die Abschaltung einer alten Version oder eines Endpunkts kann dem Konsumenten mit maschinenlesbaren Signalen angekündigt werden. Der Header Sunset ist in RFC 8594 definiert und meldet das Datum, an dem die Ressource keine Antworten mehr liefert. Der Header Deprecation wurde mit RFC 9745 standardisiert und trägt den Zeitpunkt, ab dem die Ressource als veraltet gilt (oder gelten wird), als strukturiertes Datum; das Datum hat das Format eines mit @ beginnenden Unix-Zeitstempels.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.beispiel.de/docs/v1-migration>; rel="deprecation"

In diesem Beispiel entspricht @1798761600 dem Zeitpunkt 1. Januar 2027, 00:00 UTC; v1 gilt ab diesem Datum als veraltet und wird am 1. Juli 2027 abgeschaltet. Die Relation deprecation im Header Link liefert die Adresse der Migrationsdokumentation. Der Wert der Header liegt darin, dass der Client sie automatisch protokollieren kann: Eine HTTP-Client-Schicht, die den Header sieht, erzeugt eine Warnung, und das Entwicklungsteam erfährt davon, ohne Dokumentation zu lesen.

Header ersetzen E-Mail- und Portalankündigungen nicht, sie ergänzen sie. Niemand liest Antwort-Header. Aber das Log liest sie. Liefern Sie für Anfragen an die alte Version nach dem Sunset-Datum einen klaren Statuscode wie 410 (Gone) und einen Fehler-Body, der auf die Migrationsdokumentation verweist; die Diagnose eines stillen 404 dauert Stunden.

Vertrag und Änderungsprüfung mit OpenAPI

Den API-Vertrag mit einem OpenAPI-Dokument zu definieren, verlagert die Prüfung auf inkompatible Änderungen von menschlicher Aufmerksamkeit in die Automatisierung. OpenAPI unterstützt die Markierung deprecated: true auf Ebene von Operation, Parameter und Schema; Dokumentationsgeneratoren stellen diese Markierung visuell dar.

paths:
  /v1/orders/{id}:
    get:
      deprecated: true
      summary: Bestelldetails (v1, stattdessen /v2/orders/{id} verwenden)
components:
  schemas:
    Order:
      properties:
        customerCode:
          type: string
        customer_code:
          type: string
          deprecated: true

Liegt die Vertragsdatei im selben Repository wie der Code, kann bei jeder Änderungsanfrage ein Vergleich mit der vorherigen Version erfolgen. Das Open-Source-Werkzeug oasdiff meldet inkompatible Änderungen zwischen zwei OpenAPI-Dokumenten; in der CI-Pipeline kann es so ausgeführt werden, dass es den Build bei Befunden der Fehlerstufe stoppt:

oasdiff breaking openapi-main.yaml openapi-pr.yaml --fail-on ERR

Da sich die Parameter des Werkzeugs zwischen Versionen ändern können, prüfen Sie die Dokumentation Ihrer Version. Diese Prüfung lässt sich mit den Schritten aus dem Leitfaden zur CI/CD-Pipeline mit GitHub Actions kombinieren. Eine Grenze gibt es: Der automatische Vergleich erfasst keine Verhaltensänderungen (Standardsortierung, Validierungslogik, Seitengröße). Das Schema bleibt gleich, das Ergebnis ändert sich. Dafür braucht es Vertragstests und eine Review-Checkliste.

Migrationsprozess für Integrationspartner

Sind die technischen Mechanismen bereit, entscheidet der Prozess über den Erfolg der Migration. Gehen Sie bei einer neuen Hauptversion nach diesem Ablauf vor:

  1. Inventar der Konsumenten: Halten Sie fest, zu welchem Unternehmen, welcher Anwendung und welchem technischen Verantwortlichen jeder API-Schlüssel oder jede Client-ID gehört. Ohne zu wissen, wer betroffen ist, wird kein Zeitplan angekündigt. Ein Schlüssel ohne bekannten Eigentümer ist eine Überraschung am Abschalttag.
  2. Messung der Nutzung pro Version: Werten Sie aus den Zugriffslogs die Anfragezahl pro Client und Version aus. Dieser Bericht zeigt den Fortschritt der Migration und ob das Abschaltdatum realistisch ist.
  3. Ankündigung und Zeitplan: Veröffentlichen Sie Abkündigungs- und Abschaltdatum, Migrationsdokumentation und Änderungsliste gleichzeitig. Legen Sie die Frist nach dem Entwicklungszyklus der Konsumenten und Ihren Verträgen fest.
  4. Testumgebung: Stellen Sie die neue Version früh in einer Testumgebung mit realistischen Beispieldaten bereit, in der Konsumenten sie ausprobieren können.
  5. Erinnerung und Nachverfolgung: Wenden Sie sich bei nahendem Abschaltdatum direkt an Clients, die noch die alte Version nutzen.
  6. Geplante kurze Abschaltungen (Brownout): Manche Anbieter deaktivieren die alte Version vor der Abschaltung in vorab angekündigten kurzen Intervallen; vergessene Integrationen werden so vor dem Abschalttag sichtbar. Wenden Sie diese Methode nur mit klarer Ankündigung und zu Zeiten an, die kritische Geschäftsabläufe nicht beeinträchtigen.
  7. Abschaltung und Bereinigung: Entfernen Sie nach der Abschaltung den alten Codepfad, die Dokumentation und die Tests; sonst häuft sich Versionierungsschuld an.

Zum Umfang von Versionierung und Vertragsmanagement für selbst entwickelte Geschäftsanwendungen und Partner-APIs sehen Sie sich unsere Seiten Entwicklung individueller Webanwendungen und ERP-, CRM- und API-Integrationen an.

Häufig gestellte Fragen

Sollte bei der API-Versionierung der URI-Pfad oder ein Header bevorzugt werden?

Bei Integrationen mit Geschäftspartnern ist die Hauptversion im URI-Pfad ein praktischer Standard; sie ist sichtbar und in Log-, Proxy- und WAF-Schichten leicht zu unterscheiden. Bei APIs, die häufig kleine Änderungen veröffentlichen und eine feine, datumsbasierte Versionierung wünschen, ist headerbasierte Versionierung flexibler. Was auch immer gewählt wird: Das Verhalten einer Anfrage ohne Version muss dokumentiert sein.

Ist das Hinzufügen eines neuen Feldes zur Antwort eine inkompatible Änderung?

Nach allgemein akzeptierter Auffassung nicht; das setzt aber voraus, dass Konsumenten unbekannte Felder ignorieren. Clients mit strenger Schemavalidierung können bei einem neuen Feld einen Fehler auslösen. Schreiben Sie ausdrücklich in die API-Dokumentation, dass unbekannte Felder zu ignorieren sind, und kündigen Sie neue Felder in den Versionshinweisen an.

Was ist der Unterschied zwischen den Headern Deprecation und Sunset?

Der Header Deprecation meldet den Zeitpunkt, ab dem eine Ressource als veraltet gilt; sie funktioniert weiter, sollte aber in neuen Entwicklungen nicht mehr verwendet werden. Der Header Sunset meldet das Datum, an dem die Ressource keine Antworten mehr liefert. Werden beide gemeinsam verwendet, erhält der Konsument sowohl die Warnung als auch die Frist in maschinenlesbarer Form.

Wie lange sollte eine alte API-Version unterstützt werden?

Es gibt nicht die eine richtige Dauer. Sie hängt vom Entwicklungszyklus der Konsumenten, von Verträgen mit Geschäftspartnern und vom Umfang der Änderung ab. Die Entscheidung sollte auf der Messung der Nutzung pro Version beruhen, und der Zeitplan sollte mit der Veröffentlichung der neuen Version schriftlich angekündigt werden.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge