APIs für Mobile Apps und Partner weiterentwickeln: Versionen, Kompatibilität und Abschaltung

KURZ GESAGT: Eine Website lässt sich jederzeit aktualisieren, eine App auf dem Telefon der Nutzer und das System eines Partners nicht. Ist eine API einmal ausgeliefert, sollte man davon ausgehen, dass ihre Aufrufer lange nicht aktualisieren. Unsere Regeln: Kompatible Änderungen kommen in die bestehende Version, inkompatible bekommen eine neue; die alte Version wird abgekündigt und ihre Nutzung je Aufrufer gemessen; abgeschaltet wird erst, wenn die Nutzung es erlaubt; und der Vertrag liegt in einer Datei, die die CI prüft.

Diagramm zum Lebenszyklus einer API-Version. /v1 ist aktiv und erhält nur additive Änderungen; eine inkompatible Änderung eröffnet /v2; /v1 wird danach mit Deprecation- und Sunset-Header als veraltet markiert und schließlich mit einem klaren Fehler entfernt. Darunter: Nutzungszählung für /v1 je App-Version und Partner-Schlüssel, Entfernen erst, wenn die Nutzung es erlaubt; und eine Vertragsdatei (OpenAPI), die in der CI mit dem letzten Release verglichen wird, wobei eine inkompatible Änderung außerhalb einer neuen Version scheitert.
Abbildung 1. Eine Hauptversion von aktiv über veraltet bis entfernt. Die Abschaltung folgt der Nutzung, nicht dem Kalender.

1.0 Was als kompatibel gilt

ÄnderungKompatibel?
Neues optionales Anfragefeld, neues AntwortfeldJa, sofern Clients unbekannte Felder ignorieren
Neuer EndpunktJa
Feld entfernen oder umbenennen, Typ ändernNein
Optionales Feld zur Pflicht machenNein
Neuer Enum-WertHängt davon ab, wie Clients unbekannte Werte behandeln; sicherheitshalber als inkompatibel bewerten
Fehlercodes oder Standardsortierung ändernWird oft als kompatibel behandelt, bricht aber Clients, die sich darauf verlassen

In den letzten beiden Zeilen passieren die Vorfälle. Ab der ersten Version verlangen unsere Client-Richtlinien für unbekannte Enum-Werte eine Ersatzanzeige statt eines Absturzes.

2.0 Wo die Version steht

Ein Pfadsegment wie /v1/ ist am sichtbarsten und funktioniert gut mit Logs, Gateway-Routing und Caching, daher ist es unser Standard. Ein Header wirkt sauberer, wird beim Debuggen aber leicht übersehen. Wo auch immer sie steht: Die Version ändert sich nur bei einer inkompatiblen Änderung und folgt nicht der Produktversionsnummer.

Innerhalb einer Hauptversion braucht der Server gelegentlich kleine Verhaltensunterschiede je Client-Release. Lassen Sie Clients ihre App-Version in einem Header mitsenden und entscheiden Sie auf dem Server, statt eine Kette kleiner API-Versionen anzulegen.

3.0 Der Vertrag ist eine Datei

Beschreiben Sie die API in einer Datei wie OpenAPI und legen Sie sie ins Repository. Die CI tut zweierlei: Sie vergleicht die Änderung mit dem Vertrag des letzten Releases und lässt den Build bei einer inkompatiblen Änderung scheitern, die nicht in einer neuen Version liegt, und sie führt Vertragstests aus, die prüfen, ob die Implementierung der Beschreibung entspricht.

Für Partner-APIs ist die Vertragsdatei die Quelle des Entwicklerhandbuchs, kein separat gepflegtes Dokument. Zwei getrennt geschriebene Dokumente widersprechen sich früher oder später.

4.0 Abkündigung und Abschaltung

  1. Wenn eine neue Version erscheint, tragen Antworten der alten Version Deprecation- und Sunset-Header (RFC 9745, RFC 8594), und die Dokumentation nennt das Abschaltdatum.
  2. Die Nutzung der alten Version je Aufrufer messen: welche App-Versionen und welche Partner-Schlüssel sie noch aufrufen.
  3. Für Mobile Apps eine Mindestversion einführen: Der Server veröffentlicht sie, ältere Apps fordern zum Update auf.
  4. Erst abschalten, wenn die Nutzung vertretbar niedrig ist. Danach einen klaren Fehlercode mit Update-Hinweis liefern statt eines nackten 404.

Das Abschaltdatum muss App-Store-Prüfungen und das Update-Verhalten der Nutzer berücksichtigen, und Partner brauchen Zeit, um auf ihrer Seite zu entwickeln, zu testen und auszuliefern.

5.0 Idempotenz und Wiederholungen

In Mobilfunknetzen sind Wiederholungen normal. Anlegende Endpunkte akzeptieren einen Idempotenzschlüssel: Der Client erzeugt ihn je Vorgang, und der Server liefert für denselben Schlüssel eine Zeit lang dasselbe Ergebnis. Probleme wie eine doppelt abgeschickte Bestellung werden so schon auf Protokollebene abgefangen.

Um APIs für eine App oder Partner zu entwerfen oder eine ausgeuferte API wieder in Form zu bringen, siehe Web, Cloud und Geräteverwaltung, oder Projekt besprechen.

Quellen

Häufige Fragen

Brauchen Endpunkte, die nur unser eigenes Web-Frontend nutzt, so viel Strenge?

Ein Web-Frontend, das zusammen mit dem Backend ausgeliefert und zurückgerollt wird, darf lockerer behandelt werden, solange die Vertragsprüfung weiterläuft. Sobald ein Client nicht im Gleichschritt mit dem Server releasen kann, etwa eine Mobile App, ein Mini-Programm oder ein externes System, gelten die Regeln dieses Beitrags.

Macht GraphQL Versionierung überflüssig?

Bei GraphQL ist es üblich, auf Versionen zu verzichten und durch neue Felder und als veraltet markierte Felder weiterzuentwickeln. Das ist dieselbe Kompatibilitätsdisziplin in anderer Form. Bevor ein Feld entfernt wird, muss man auch hier wissen, wer es noch abfragt.

Wie lange sollte eine alte Version bestehen bleiben?

Eine allgemeine Antwort gibt es nicht; es hängt davon ab, wie schnell Nutzer aktualisieren und wie die Release-Zyklen der Partner aussehen. Wir entscheiden nach tatsächlicher Nutzung und nennen das Abschaltdatum schon beim Release der neuen Version, damit Aufrufer planen können.

Wir haben intern umgebaut. Muss sich die öffentliche API mitändern?

Die API beschreibt ein Versprechen nach außen, nicht die interne Struktur. Auf dem Server abzubilden und den externen Vertrag stabil zu halten, ist bei einem internen Umbau meist der günstigste Weg.