Doku

Tippe ein Stichwort. Mit Esc schließt du die Suche.
EN
Anmelden Kostenlos starten
Entwickler/Grundlagen

Eine Version, und ein Protokoll jeder Änderung.

Die API hat eine Version, /v1. Änderungen erscheinen innerhalb davon, und das Änderungsprotokoll hält jede fest, auch die, die einen Client brechen können.

Was die API heute tut

ThemaVerhalten
URL-VersionJede Operation wird unter /v1 ausgeliefert. Eine andere Version und ein /v2 gibt es nicht.
Request-Header X-API-VersionWird akzeptiert. Jeder nicht leere Wert kennzeichnet die Anfrage als Anfrage der öffentlichen API, was ihr den data-Umschlag gibt und bei GET /monitors die Cursor-Paginierung. Der Wert selbst wird nicht gelesen.
api_version eines SchlüsselsJeder Schlüssel speichert eine, standardmäßig 2026-05-07. GET /me gibt sie zurück. Am Verhalten ändert sich dadurch nichts.
Header Deprecation und SunsetDie API sendet keinen von beiden.
 
curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "X-API-Version: 2026-05-07"

Der Aufruf oben verhält sich genau wie einer ohne den Header, weil eine Anfrage mit API-Schlüssel das Verhalten der öffentlichen API ohnehin bekommt.

Wie dich Änderungen erreichen

Das Änderungsprotokoll kennzeichnet jede Änderung am Vertrag als breaking, added, changed, deprecated oder documented und hat einen Filter „Breaking only“. Es wird aus dem Verlauf der OpenAPI-Datei erzeugt. Behalte es im Blick, oder die OpenAPI-Datei selbst, für die Operationen, die du nutzt.

Beabsichtigt ist, dass eine Änderung, die Clients bricht, eine eigene Version bekommt, /v2, mit 12 Monaten Parallelbetrieb und den Headern Deprecation und Sunset. Das ist eine Absicht, kein Verhalten, auf das du testen kannst: Heute gibt es weder ein /v2 noch einen solchen Header, und das Änderungsprotokoll zeigt Breaking Changes, die innerhalb von /v1 vorgenommen wurden. Richte dich nach dem Änderungsprotokoll, nicht nach einem Header.

Einen toleranten Client schreiben

  • Ignoriere Felder der Antwort, die du nicht kennst; neue erscheinen als added.
  • Verlass dich nicht auf die Reihenfolge der Schlüssel oder von scopes in GET /me.
  • Verzweige nach error.code, nicht nach error.message. Siehe Antworten und Fehler.
  • Sichere die Operationen, die du nutzt, mit Tests ab. Ein geänderter nötiger Scope steht im Änderungsprotokoll als breaking.

Typische Fehler

  • X-API-Version senden, um ein altes Verhalten festzuhalten. Der Header hält nichts fest.
  • Die api_version eines Schlüssels ändern, um eine andere Antwort zu bekommen. Eine solche Wirkung gibt es nicht.
  • Auf einen Sunset-Header warten, bevor du nach Entfernungen schaust. Lies das Änderungsprotokoll.
  • Gegen /v2-Pfade bauen. Sie existieren nicht.
Volle Größe ↗