API-Versionierung

Wie sich die Diveity API entwickelt – welche Änderungen Clients beeinträchtigen und wie wir sie kommunizieren.

Regeln zur Abwärtskompatibilität

Diese Regeln beschreiben, was sicher ist und was breaking an jedem Endpunkt von /api/v1 ist.

Das Hinzufügen eines Feldes ist non-breaking – Clients ignorieren unbekannte Felder.
Das Entfernen eines Feldes ist breaking – erfordert eine neue API-Version.
Das Umbenennen eines Feldes ist breaking – erfordert eine neue API-Version.
Das Ändern des Typs eines Feldes (z.B. String → Zahl) ist breaking – erfordert eine neue API-Version.

Das Hinzufügen eines OPTIONALEN Abfrageparameters ist non-breaking.
Das Entfernen eines optionalen Abfrageparameters ist breaking – Clients, die davon abhängen, verlieren stillschweigend Funktionalität.

Wenn wir eine neue Hauptversion der API veröffentlichen, tritt die vorherige Version in einen dokumentierten Sunset-Pfad ein.

Mindestens 6 Monate Vorankündigung zwischen der Deprecation-Ankündigung und dem End-of-Life.
Während des Deprecation-Fensters enthält jede Antwort den RFC 9745 Deprecation-Header (?1) und den RFC 8594 Sunset-Header (HTTP-Datum des EOL).
30 Tage vor dem Sunset-Datum beginnen Brownouts: Ein kleiner Teil der Anfragen gibt 503 Service Unavailable zurück, um verbleibende Integrationen aufzudecken. Der Anteil steigt im Laufe des Zeitraums von 0% auf 25%.
Entwickler, deren API-Schlüssel in den letzten 30 Tagen eine veraltete Version verwendet haben, erhalten einmal pro Hauptversionsübergang eine E-Mail.
Nach dem Sunset-Datum wird die Version entfernt; Anfragen daran geben 404 zurück.