Versionen und Kompatibilität

Die API hat eine Hauptversion, /v1, und diese wächst nur. Eine Integration, die Sie heute schreiben, funktioniert weiter, während neue Funktionen hinzukommen: Nichts, worauf sie sich verlässt, wird umbenannt, entfernt oder bekommt eine neue Bedeutung.

Die Versionsnummer

Die API hat eine Versionsnummer wie 1.62.0. Die Nummer ändert sich mit jedem Release:

• die Minor-Nummer, wenn etwas hinzukommt: ein Endpunkt, ein Feld, ein Ereignis;
• die Patch-Nummer, wenn eine Beschreibung oder ein Meldungstext korrigiert wird und sich sonst nichts ändert.

Die Version, die unter einer Adresse läuft, können Sie jederzeit abfragen:

Auch GET /v1/health hat ein Feld version, das ist aber die Version des Sursa-Release, das die Adresse bedient, nicht die Version der API.

Eine Minor-Version wählen Sie nicht aus: Jede Anfrage wird von der aktuellen bedient. Dank der folgenden Regeln ist das sicher.

Was sich in /v1 ändern kann

Diese Änderungen können mit jeder Minor-Version kommen. Schreiben Sie Ihre Integration so, dass sie dadurch nicht beeinträchtigt wird:

• Neue Endpunkte.
• Neue optionale Parameter und Felder in Anfragen. Anfragen ohne sie verhalten sich wie bisher.
• Neue Felder in Antworten, Objekten und Ereignissen.
• Neue Werte von Aufzählungen in Antworten, etwa ein neuer Kartenstatus oder ein neuer Ereignistyp.
• Neue Fehlercodes und neue Antwort-Header.
• Limits, die weniger streng werden: eine größere Maximallänge, ein breiterer Wertebereich.
• Umformulierte message-Texte von Fehlern und umformulierte Beschreibungen.

Was Ihr Code tolerieren muss

• Ignorieren Sie Felder, die Sie nicht kennen. Brechen Sie nicht ab, wenn eine Antwort mehr Felder hat als erwartet, und verwenden Sie keine strikten Schemas, die sie ablehnen.
• Akzeptieren Sie unbekannte Enum-Werte. Jede Aufzählung in einer Antwort kann wachsen. Behandeln Sie einen unbekannten Wert als „Sonstiges“ und nicht als Fehler.
• Überspringen Sie unbekannte Ereignistypen, sowohl in Webhooks als auch in Streams.
• Behandeln Sie unbekannte Fehlercodes nach ihrem HTTP-Status: siehe Fehler.
• Verlassen Sie sich nicht auf die Reihenfolge der Felder in JSON-Objekten oder auf den genauen Wortlaut von Meldungen.

Was sich in /v1 nie ändert

• Ein Pfad, ein Parameter, ein Feld oder ein Enum-Wert wird nie umbenannt oder entfernt.
• Der Typ eines Felds ändert sich nie, und ein Feld bekommt nie eine neue Bedeutung, etwa neue Einheiten.
• Eine Anfrage, die heute angenommen wird, wird später nicht abgelehnt.
• Der Statuscode einer erfolgreichen Antwort bleibt derselbe.
• Fehlercodes behalten ihre Bedeutung, und das Feld detail von Fehlerantworten behält seine Form.
• Ereignistypen werden nie umbenannt oder entfernt, und ihr data bekommt nur neue Felder hinzu.

Inkompatible Änderungen

Sollte je eine inkompatible Änderung nötig sein, erscheint sie als neue Hauptversion, etwa /v2, neben /v1. /v1 funktioniert unverändert weiter, und beide laufen parallel.

Wenn eine Route eingestellt werden soll:

1. Die Route wird in der Spezifikation als deprecated markiert und im Changelog mit dem Datum aufgeführt, an dem sie abgeschaltet wird.
2. Antworten der Route tragen die Header Deprecation: true und Sunset: <date>.
3. Die Route funktioniert nach der Ankündigung noch mindestens 180 Tage. Organisationen, deren API-Schlüssel sie verwenden, werden mindestens 90 Tage vorher schriftlich informiert.
4. Nach dem Sunset-Datum antwortet sie weitere 90 Tage mit 410 und dem Code api.gone.

Achten Sie in Ihren Protokollen oder Ihrem Monitoring auf den Header Deprecation: Er ist das früheste Signal, dass eine Route, die Sie verwenden, wegfällt.

Auf dem Laufenden bleiben

Das Changelog dieses Portals führt jedes Release auf, mit dem, was hinzugekommen ist und was als veraltet markiert wurde. Bevor Sie Ihre eigene Integration aktualisieren, vergleichen Sie ihren Code mit den Einträgen seit der Version, für die Sie sie gebaut haben.