Die wichtigsten Grundlagen zur API-Versionierung bei Shopify: Das solltest du wissen

Bevor wir die API Versionierung bei Shopify im April 2019 vorgestellt haben, konnten Apps lediglich mit unserer neuesten Form der APIs interagieren. Im Zuge der Veröffentlichung neuer Funktionen für Händler*innen, haben sich die APIs, die mit diesen Funktionen verwoben waren, ebenfalls weiterentwickelt. So mussten sich Apps schnell an die neue Art, wie die Dinge nun laufen, anpassen, um weiterhin zu funktionieren. 

Dies hat die Entwickler regelmäßig vor Herausforderungen gestellt. Es war nicht leicht zu erkennen, wann welche Änderungen an den APIs vorgenommen wurden und wie sie sich auf verschiedene Apps auswirken. 

Um dieses Problem zu lösen und zukünftige Änderungen für unsere Partner planbarer zu machen, haben wir im April 2019 die API-Versionierung eingeführt. Wir nehmen Änderungen an den APIs nicht mehr kontinuierlich vor, sondern veröffentlichen diese in regelmäßigen Abständen im Rahmen einer neuen Version. Die vorherige Version steht dabei parallel weitere neun Monate zur Verfügung, sodass du genug Zeit hast auf die Änderungen zu reagieren. 

In diesem Beitrag erklären wir, was es mit den unterschiedlichen API-Versionen auf sich hat, was die Änderungen für dich und deine Kund*innen bedeutet und worauf du achten solltest.

So funktioniert die API-Versionierung

Vor allem in diesem Jahr gibt es zahlreiche Änderungen an den bestehenden APIs. Um besser verstehen zu können, was in 2020 auf dich und deine Kund*innen zukommt, haben wir die Grundlagen der API-Versionierung für dich zusammengefasst:

1. Wir veröffentlichen vierteljährlich eine neue Version 

Wir veröffentlichen jeweils zu Beginn eines Quartals – das heißt am oder um den 1. Januar, 1. April, 1. Juli und 1. Oktober – eine neue API-Version, die im Format Jahr-Monat nach ihrem Veröffentlichungsdatum benannt wird. Die neueste Version 2020-04 steht seit dem 01. April 2020 zur Verfügung. So siehst du sofort zu welchem Zeitpunkt und in welcher Reihenfolge die unterschiedlichen Versionen veröffentlicht wurden.

2. Versionen werden mindestens ein Jahr lang unterstützt 

Jede API-Version läuft mindestens ein Jahr lang stabil und wird nur im Falle eines kritischen Sicherheits-Fixes geändert. Danach wird sie nicht mehr unterstützt und kann nicht mehr von Apps verwendet werden, weshalb sie vorher auf eine neuere Version migriert werden sollte. 

Jede neue API-Version kann Änderungen enthalten, die nicht mit allen Apps kompatibel sind. Um herauszufinden, ob das bei einer bestimmten App der Fall ist, können Entwickler*innen vorab im Partner-Dashboard testen, ob die Anwendung stabil läuft. Falls es dabei zu Problemen kommt, bleibt genügend Zeit die App entsprechend anzupassen.

Apps müssen nicht zwingend alle drei Monate auf eine neue API-Version umgestellt werden, da die vorherigen APIs parallel weiterlaufen. Das bedeutet allerdings, dass alle Funktionen, die erstmals in späteren Versionen veröffentlicht wurden, nicht genutzt werden können.

3. Jede API-Version erhält eine eigene URL

Mit der Veröffentlichung der API 2020-04 stehen vier stabile API-Versionen gleichzeitig zur Verfügung. Wenn eine App eine bestimmte API verwenden soll, muss der Versionsname in der URL angegeben werden. Die neueste Version 2020-04 der Storefront API wird beispielsweise über die URL /api/2020-04/graphql.json aufgerufen.

4. Apps, die keine bestimmte Version anfordern, werden auf die älteste stabile Version umgeleitet 

Vor April 2019 gab es keine API-Versionen, weshalb Apps auch keine spezifische Version in ihrer URL anfordern konnten. Es kann vorkommen, dass bei einigen dieser Apps die URL immer noch nicht aktualisiert wurde. Damit diese weiterhin funktionieren, werden sie automatisch auf eine stabile Version umgeleitet. 

Dieses Konzept gilt auch für Apps, die veraltete, nicht mehr unterstützte API-Versionen aufrufen. Wenn eine App beispielsweise weiterhin 2019-07 anfordert, nachdem diese nicht mehr unterstützt wird, wird automatisch die Version 2019-10 verwendet. 

Allerdings empfehlen wir den Entwickler*innen ihre Apps auf eine stabile Version umzustellen, um sicherzustellen, dass sie weiterhin reibungslos funktionieren. 

5. Neue Funktionen können mit Release Candidates vorab getestet werden 

Um neue Funktionen bereitzustellen, ohne die stabilen APIs zu beeinträchtigen, verwenden wir sogenannte Release Candidates. Das sind Vorabversion der nächsten API. Sie können über die URL im Jahr-Monat-Format aufgerufen und eingesetzt werden.

Die API-Release Candidates sind jeweils drei Monate vor der Veröffentlichung der stabilen Version verfügbar. So können Entwickler*innen sehen, welche Änderungen und Funktionen beim nächsten Update veröffentlicht werden und so früh wie möglich mit der Aktualisierung ihrer Apps beginnen.

Anders als bei den stabilen API-Versionen entwickeln wir Release Candidates bis zur Veröffentlichung kontinuierlich weiter. Aus diesem Grund sollten sie nur zu Testzwecken genutzt werden.

Da wir nun die Grundlagen der API Versionierung bei Shopify durchgegangen sind, lass uns auf die wesentlichen Informationen für das Jahr 2020 schauen.

Dieser Beitrag könnte dich ebenfalls interessieren: Ein Insider-Blick auf die Technologie hinter Shopify.

Die API-Versionen 2019-04 und 2019-07 werden zum 01.Juli 2020 eingestellt 

Diese Änderungen kommen im Juli auf dich und deine Kund*innen zu 

Entwickler sollten noch vor dem 01. Juli 2020 testen, ob ihre Apps auf der API 2019-10 stabil laufen und sie gegebenenfalls anpassen. Denn im Vergleich zu den vorherigen Versionen enthält die API 2019-10 erhebliche Änderungen, die den Funktionsumfang einiger Apps und damit auch die User Experience deutlich beeinträchtigen können.

1. Wir stellen auf die cursorbasierte Pagination um

Die Paginierung wird verwendet, um die Abfrage großer Datenmengen wie Produkte, Bestellungen oder Suchergebnisse zu strukturieren und zu beschleunigen. Dabei wird der gesamte Datensatz in kleinere Blöcke unterteilt. Statt alle Daten auf einmal aufzurufen, wird mit jeder Anfrage nur eine kleine Teilmenge geladen und angezeigt. Ein typisches Beispiel sind Produkte in einem Onlineshop, die auf mehreren Seiten dargestellt werden. 

Bisher wurden solche Datensätze in Shopify-Shops anhand von zwei Parametern seitenbasiert paginiert. Diese geben an, welche Seite (page) mit wie vielen Ergebnissen (count) aufgerufen werden soll. Wenn eine bestimmte Seite geöffnet wird, werden alle Daten bis zu dieser Seite geladen und dann wieder verworfen bis die richtigen Ergebnisse gefunden wurden. Bei Shops mit vielen Produkten und entsprechend hohen Seitenzahlen führt das zu langen Ladezeiten.

In der API-Version 2019-10 wird die seitenbasierte Paginierung deshalb von der cursorbasierten Paginierung abgelöst. Sie funktioniert wie ein Lesezeichen: statt den gesamten Datensatz immer wieder neu zu lesen, beginnt jede neue Anfrage genau dort, wo die vorherige aufgehört hat. Das führt zu erheblich verkürzten Ladezeiten und wirkt sich positiv auf die Performance des Shops aus.

2. Das Featured-Feld wird aus Collects entfernt

Manuelle Kategorien (Custom Collections) sind ein weiteres wichtiges Element, um Produkte zu organisieren. Händler*innen können diese benutzerdefinierten Kategorien selbst erstellen und ihnen einzelne Produkte zuordnen. 

Anstatt das gesamte Produktsortiment zu durchstöbern, können Nutzer*innen damit gezielt nach einzelnen Kategorien filtern und finden schneller was sie suchen. Das geschieht über den Collect-Endpoint, der die Produkte mit den jeweiligen Kategorien verbindet. 

Mit dem Featured-Feld konntest du bisher einzelne Beziehungen gesondert markieren. In der API-Version 2019-10 ist es im Collect-Endpoint jedoch nicht mehr verfügbar. 

Falls du den Collect-Endpoint in Onlineshops verwendest und er noch nicht auf eine stabile API umgestellt wurde, erhältst du im Partner-Dashboard eine entsprechende Benachrichtigung, auch wenn du das Featured-Feld nicht verwendest. 

3. GraphQL Admin ID wurde zu Webhooks hinzugefügt

Webhooks werden verwendet, wenn ein bestimmter Prozess in einer Anwendung aufgrund eines Ereignisses in einer separaten Anwendung gestartet werden soll. Händler*innen können mit Webhooks beispielsweise Benachrichtigungen an das Warenwirtschaftssystem senden, wenn eine Bestellung abgeschickt wurde oder eine neue Zahlung bei PayPal eingegangen ist.

Wie die meisten unserer APIs sind auch unsere Webhooks versioniert, damit wir regelmäßig neue Funktionen bereitstellen können. In der neuen Version haben wir die graphql_admin_id hinzugefügt, die GraphQL-Aufrufe einfacher macht. Um sie nutzen zu können, sollten Webhook-APIs auf 2019-10 oder höher umgestellt werden.

4. Mit der Inventory-API können Händler*innen mehrere Standorte einrichten

Händler*innen können mehrere Standorte zu ihrem Onlineshop hinzufügen, um ihr Inventar und Bestellungen von unterschiedlichen Locations zu verwalten. 

Ein Standort kann ein physischer Ort wie ein Einzelhandelsgeschäft oder ein Lager sein, an dem du Produkte verkaufst. Auch Apps, die Bestellungen für die Händler*innen ausführen, gelten als Standort. Mithilfe von Apps können verschiedene Aktivitäten wie der Verkauf von Produkten, die Abwicklung und der Versand von Bestellungen und die Verwaltung von Warenbeständen ausgeführt werden.

Mit der Version 2019-10 haben wir einige Änderungen an der Inventory-API vorgenommen: Alle Apps, die veraltete APIs verwenden, können in Shops mit mehr als einem Standort nicht mehr installiert werden. 

Wenn die App bereits installiert wurde, können Händler*innen in diesem Shop keine weiteren Standorte hinzufügen. Deshalb sollten Entwickler ihre Apps rechtzeitig auf eine stabile Version der Inventory-API umstellen, um zu verhindern, dass Händler auf andere Apps umsteigen.

 Wenn deine Kund*innen private Apps nutzen, die speziell für ihren Shop entwickelt wurden, wirst du auf der Seite „Standorte“ im Partner-Dashboard darüber benachrichtigt, welche Apps aktualisiert werden müssen. Wir empfehlen in dem Fall die Entwickler direkt zu kontaktieren.

Wie du Standorte aktivierst oder einrichtest und das Inventar verwaltest, erfährst du in unserem Help Center.

Mit der API-Versionierung kannst du dich frühzeitig auf Änderungen einstellen

Wir wissen, dass jede Weiterentwicklung unserer Plattform auch für unsere Partner*innen zusätzlichen Aufwand bedeutet. Mit der API-Versionierung liefern wir einen Fahrplan für zukünftige Änderungen und machen die Nutzung von Apps planbarer. 

Jede neue Version steht mindestens ein Jahr lang zur Verfügung und neue Funktionen können schon vorab getestet werden. Damit bleibt dir mehr Zeit, um dich auf zukünftige Änderungen einzustellen und entsprechende Maßnahmen zu ergreifen.

Wenn du Fragen hast, chatte mit uns in den API-Foren oder melde dich im Support-Bereich deines Partner-Dashboards an.