API-Versionierung: Ohne Clients zu brechen

Kurz: Wege, eine Schnittstelle weiterzuentwickeln, ohne dass bestehende Apps und Programme, die sie nutzen, plötzlich nicht mehr funktionieren.

Genauer: Sobald fremde Programme eine API nutzen, bricht jede Änderung potenziell deren Funktion. Man unterscheidet abwärtskompatible Änderungen (neue optionale Felder, neue Endpunkte) von brechenden (Feld entfernt oder umbenannt, anderer Typ, geänderte Bedeutung). Versionierung macht brechende Änderungen möglich, ohne alle Nutzer zu zwingen, sofort umzustellen.

Im Detail

Versionierungsarten

• Im Pfad: /v1/kunden, /v2/kunden. Einfach und sichtbar, daher sehr verbreitet.
• Im Header: Accept: application/vnd.firma.v2+json oder ein eigener Header. Saubere URLs, aber schwerer zu testen.
• Als Parameter: ?version=2. Selten empfohlen.
• Datumsbasiert: Der Client legt ein Stichtagsdatum fest (so macht es zum Beispiel Stripe) und bekommt das damalige Verhalten.

Ohne neue Version auskommen

Viele Änderungen brauchen keine neue Version: Neue Felder hinzufügen, nie bestehende entfernen oder umdeuten, neue Werte vorsichtig einführen. Clients sollten unbekannte Felder ignorieren (Tolerant Reader). Aufzählungswerte (Enums) sind kritisch, wenn Clients bei unbekanntem Wert abstürzen.

Auslaufen lassen

Eine alte Version wird nicht von heute auf morgen abgeschaltet. Übliche Schritte: Ankündigung mit Frist, Hinweise in den Antworten (Deprecation- und Sunset-Header), Nutzungsmessung pro Version und gezielte Information der letzten Nutzer. Pflege möglichst wenige Versionen gleichzeitig.

Tests

Verbraucherorientierte Vertragstests (Consumer-driven Contract Tests, zum Beispiel mit Pact) prüfen automatisch, ob eine Änderung die Erwartungen der Clients verletzt. Eine OpenAPI-Beschreibung lässt sich zwischen Versionen vergleichen, um brechende Änderungen zu erkennen.

Siehe auch: REST-API-Design, APIs, Semantische Versionierung