AthausDoku

REST-API: Version

Die Version ist der Pfad v1. Der Kopf Athaus-Version, die Ausgabe und was nie ein Bruch ist.

Zuletzt aktualisiert:

Die Version der API ist ihr Pfad: v1. Innerhalb von v1 kommt nur etwas hinzu: neue Operationen, neue optionale Mitglieder, neue Werte dort, wo die Doku eine Liste offen nennt. Ein Client ignoriert Mitglieder, die er nicht kennt. Eine Änderung, die bestehende Clients bricht, bekommt /v2, und /v1 läuft danach noch mindestens 12 Monate daneben.

Der Kopf Athaus-Version

Du musst keinen Kopf senden, und er sagt dir nichts, was du brauchst. Jede Antwort nennt v1 im Kopf Athaus-Version und in GET /v1/me als apiVersion. Wenn du ihn sendest, nehmen wir v1 und 1 an.

curl https://api.athaus.ai/v1/me   -H "Authorization: Bearer ath_live_..."   -H "Athaus-Version: v1"

Jeder andere Wert ist ein 400 mit api_version_unsupported, damit ein Client, der etwas Unbekanntes verlangt, es erfährt. Ein Key hängt an keiner Version.

Das Release

v1 ist die Version, 1.1 ist das Release: Jede Antwort auf einen Aufruf mit gültigem Key nennt es im Kopf Athaus-Release und im Feld info.version des OpenAPI-Dokuments. Es zählt die Ergänzungen innerhalb von v1 (1.0, 1.1, 1.2) und ist nur ein Name: Keine Anfrage kann ein Release wählen, und nichts verhält sich nach ihm anders. Die Releases stehen mit Datum in den Neuigkeiten. Ein Release entsteht mit einem Eintrag dort und einer Erhöhung der Konstante API_RELEASE, in dem Pull Request, der die Ergänzungen ausliefert, oder in einem kleinen danach.

Was ein Bruch ist

Ein Mitglied fällt weg oder ändert seine Bedeutung, ein Wert einer Aufzählung fällt weg, ein Pfad verschwindet. Dafür gibt es eine neue Version, /v2. Bis es einen Bruch gibt, gibt es nur v1.

Was kein Bruch ist

Das kann jederzeit ohne neue Version geschehen. Bau deinen Client so, dass er es verträgt: unbekannte Mitglieder ignorieren, unbekannte Werte einer Aufzählung behandeln, den Cursor und das Page Token nicht lesen.

  • Neue Ressourcen und neue Operationen.
  • Neue optionale Parameter in einer Anfrage.
  • Neue Felder in einem Antwortobjekt.
  • Neue Werte in einer Aufzählung. Clients müssen Werte behandeln, die sie nicht kennen.
  • Neue Ereignisarten.
  • Neue Fehlercodes und neue Fehlerarten. Verzweige auf einen bekannten Code und behandle alle anderen nach ihrem HTTP-Status.
  • Eine Änderung des Fehlertexts für Menschen.
  • Eine andere Reihenfolge der Schlüssel in einem Objekt.
  • Eine Änderung von Inhalt oder Länge eines Cursors. Ein Cursor ist undurchsichtig.
  • Eine Änderung von Länge oder Zeichensatz einer Objektkennung.
  • Neue Köpfe in einer Antwort.

Abkündigung

Zugesagt ist ab dieser Version: Was wegfällt, wird zuerst abgekündigt, mindestens 12 Monate vor dem Ende. Die Antworten tragen dann die Köpfe Deprecation und Sunset, die beide Daten nennen, und die Referenz markiert das Element als abgekündigt. Eine Frist wird nie verkürzt. Heute ist nichts abgekündigt.

Weiter lesen

Auf dieser Seite