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
So funktioniert die Versionierung
Eine Nummer im Pfad, geändert nur bei einer inkompatiblen Änderung.
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.
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.
Abschaltdatum angekündigt
Ein Abschaltdatum steht fest
Sobald ein Abschaltdatum feststeht, enthalten Antworten zusätzlich diesen Header. RFC 8594 definiert das Datum, an dem die Version nicht mehr antwortet.
Ersatzversion verlinkt
Die Ersatzversion ist angegeben
Zusammen mit dem Abschaltdatum verweist ein Link mit rel="successor-version" Ihren Client auf die Ersatzversion.
Beispielhafte Header-Werte, keine Ankündigung zur Abschaltung.
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