Diese Seite sagt, worauf Sie sich verlassen können, wenn Sie gegen die OutBIG-API bauen — und was passiert, sollte sich das je ändern. Es ist eine Zusage, keine Absichtserklärung: Der Sinn des Aufschreibens ist, dass Sie damit planen können.
Die Version steht im Pfad: /api/v1. Es gibt keinen Versions-Header und keine Aushandlung über den Content-Type — die Adresse, die Sie aufrufen, ist der Vertrag, den Sie bekommen.
Eine brechende Änderung bekommt einen neuen Pfad (/api/v2). /api/v1 ändert seine Form nicht unter Ihnen weg.
Einen Endpunkt, ein Feld oder einen Statuscode entfernen. Ein Feld umbenennen. Typ oder Einheit eines Feldes ändern. Einschränken, was ein Parameter annimmt. Einen Pflichtparameter hinzufügen.
Auch die Bedeutung eines bestehenden Wertes zu ändern zählt dazu, selbst wenn der Typ gleich bleibt — etwa wenn amountCents je aufhörte, Cent zu sein.
Einen Endpunkt, ein Feld, einen optionalen Parameter oder einen neuen Wert in einer bestehenden Aufzählung hinzufügen. Den Wortlaut von message und hint in Fehlerantworten — verzweigen Sie auf error.code, der ist stabil.
**Ignorieren Sie unbekannte Felder, statt daran zu scheitern.** Ein Client, der unerwartete Felder ablehnt, bricht bei einer ergänzenden Änderung — und ergänzende Änderungen sind die häufigsten.
Sollte /api/v1 je zurückgezogen werden, trägt jede Antwort daraus die Header Deprecation und Sunset (RFC 8594) **mindestens 6 Monate** vorher, und auf dieser Seite steht das Datum.
Bis dahin werden diese Header nicht gesendet. Ein Deprecation-Header auf einer Version, die nicht abgekündigt ist, wäre eine Falschaussage über den Ist-Zustand — da fallen wir lieber durch eine automatische Prüfung.
Sunset trägt das Datum, an dem der Endpunkt aufhört zu antworten. Deprecation trägt das Datum, an dem die Abkündigung in Kraft trat. Beide als HTTP-Datum in UTC.
In den Antwort-Headern, auf dieser Seite und in /llms.txt. Es gibt keinen Verteiler — die API braucht kein Konto, also gibt es auch keine Adresse, an die wir schreiben könnten.
Wenn Sie sich auf diese API verlassen und direkt benachrichtigt werden möchten, sagen Sie unter office@ostheimer.at Bescheid; dann geschieht das.