Die Storefront API wird nach dem Versionless-Prinzip weiterentwickelt. Das bedeutet, dass ITscope in der Regel nur Änderungen vornehmen wird, die abwärtskompatibel sind. Dadurch werden Nutzer der Storefront API nicht genötigt, Versionierungsschritte mitzugehen. Es wird allerdings seltene Fälle geben, in denen Änderungen nicht abwärtskompatibel sind. Dazu zählt zum Beispiel das Löschen von Feldern. Diese Änderungen werden weit im Voraus kommuniziert, bevor sie wirksam werden.
API Lifecycle
Der Lebenszyklus der Storefront API gilt für Endpunkte, Felder und Übergabeparameter. Während der Nutzungsphase stehen die Endpunkte, Felder und Übergabeparameter zur normalen Verwendung bereit, und werden permanent weiterentwickelt.
Entscheidet sich ITscope aufgrund von zwingenden Änderungen, bestimmte Endpunkte, Felder oder Übergabeparameter in Zukunft nicht mehr zu unterstützen, wird dies unter „Abkündigungen“ aufgeführt und frühzeitig angekündigt. Endpunkte werden dazu mit dem Sunset HTTP Header markiert. Für Felder wird dies in die openAPI Property Description geschrieben. Dabei wird ein festes Datum kommuniziert, bis wann der Endpunkt noch nutzbar ist. Die Phase des Sunset dauert in der Regel 12 Monate.
Felder und Endpunkte die als Sunset markiert wurden, werden nach 12 Monaten zu Deprecated. Für Felder wird dies in die openAPI Property Description geschrieben. OpenAPI 3.0 hat dafür das Feld deprecated. Für Endpunkte gibt es den Deprecated HTTP Header. Neben dem Deprecated wird ein festes Datum stehen, bis wann diese Phase läuft. Diese Phase dauert in der Regel 6 Monate, in der es keinen Support mehr gibt.
Nach den 6 Monaten werden Endpunkte, Felder und Übergabeparameter gelöscht.
Die ganze Phase von der Abkündigung bis zum Entfernen eines Endpunkts, Felds oder Übergabeparemeter dauert also 18 Monate: 12 Monate Sunset und danach 6 Monate Deprecated.
Versionsnummer
Obwohl die Storefront API Versionless ist, wird im openAPI-Dokument eine Versionsnummer angegeben – da dies Pflicht ist. Dabei wird Semantische Versionierung nach dem Schema {MAJOR}.{MINOR}.{PATCH} eingesetzt, damit Sie als Nutzer der Storefront API schnell einen Überblick gewinnen, ob in Zukunft Anpassungen an ihrer Client-Implementierung notwendig sind. Die aktuelle Version der Storefront API ist 1.0.0.
Jede Änderung die abwärtskompatibel ist, erhöht die PATCH-Version. Es stehen neue Endpunkte, Felder oder Übergabeparameter zur Verfügung.
Jede Änderung die Endpunkte, Felder oder Übergabeparameter im Sunset erhöht die MINOR-Version. Damit wird deutlich, das langfristig Anpassungen am Client notwendig sein könnten.
Die MAJOR-Version wird voraussichtlich nie erhöht.
Angenommen Sie nutzen die Storefront API der Version 1.1.1. Die aktuelle Version ist aber 1.1.9. In diesem Fall müssen Sie nichts unternehmen. Wenn die aktuelle Version 1.2.1. wäre, müssten Sie prüfen, ob die unter „Abkündigungen“ aufgeführten Änderungen ihren Client betreffen.
Abkündigungen
Sunset
< nichts >
Deprecated
< nichts >