Zum Inhalt springen

ecentic API: Versionierung.

Die Version steht im Pfad. Eine Integration, die eine Version festlegt, behält den Vertrag, für den sie entwickelt wurde, und verliert ihn nie ohne Vorwarnung.

Versionierung im URL-Pfad · 180 Tage Vorlauf · Deprecation- und Sunset-Header

01

So funktioniert die Versionierung

Eine Nummer im Pfad, geändert nur bei einer inkompatiblen Änderung.

Fixierte Anfrage- und Antwortversion

Die aktuelle Version ist v1 und wird unter /api/v1 bereitgestellt. Jede Antwort gibt die Version zusätzlich in einem API-Version-Header zurück, damit ein Client, der einer Weiterleitung oder einem Link folgt, bestätigen kann, womit er tatsächlich kommuniziert.

Zur selben Version hinzufügen

Additive Änderungen werden innerhalb einer Version ausgeliefert: neue Endpunkte, neue optionale Anfragefelder oder neue Felder in einer bestehenden Antwort. Behandeln Sie unbekannte Antwortfelder als Vorwärtskompatibilität und nicht als Fehler.

Neuen Versionspfad starten

Eine Änderung, die ein Feld entfernt, umbenennt, einen Typ einschränkt oder die Bedeutung eines bestehenden Werts verändert, ist ein Breaking Change und wird als neuer Versionspfad neben dem alten ausgeliefert – niemals direkt an dessen Stelle.

02

Deprecation und Sunset

Zwei Standard-Header und ein ausreichend langes Zeitfenster, um darauf zu reagieren.

Wählen Sie einen Header aus, um zu sehen, was er Ihrem Client mitteilt.

Abkündigung angekündigt

Eine Version wird abgekündigt

Jede Antwort einer abgekündigten Version enthält diesen Header. Er kündigt die Abkündigung gemäß RFC 9745 an.

Format des Deprecation-Headers

Beispielhafte Header-Werte, keine Ankündigung zur Abschaltung.

03

Was nicht versioniert wird

Discovery-Dokumente führen stattdessen die Version ihres jeweiligen Protokolls.

Die .well-known-Discovery-Dokumente werden nach dem jeweils implementierten Protokoll versioniert, nicht nach der ecentic API-Version — das UCP-Profil enthält eine UCP-Version, die MCP-Serverkarte eine Protokollversion und so weiter. Die Version direkt im Dokument auszulesen, ist immer korrekt; sie aus der ecentic API-Version abzuleiten, nicht.

ecentic API-Vertrag
/api/v1
API-Version: 1
Discovery-Protokollvertrag
.well-known
Version im Dokument lesen