Zum Hauptinhalt springen

API-Versionierung

Die öffentliche API verwendet datierte Versionen — dasselbe Schema wie Shopify —, damit sich eine Version, gegen die Sie entwickeln, nicht unter Ihnen verändert. Datierte Versionen sind die grobe Grenze für Breaking Changes; innerhalb einer Version entwickelt sich das Schema weiterhin ausschließlich additiv.

Versionsnamen​

Eine Version heißt YYYY-MM, wobei der Monat ein Quartalsbeginn ist: 2026-01, 2026-04, 2026-07, 2026-10. Eine neue datierte Version wird nur dann herausgegeben, wenn es einen Breaking Change gibt — Quartale ohne Breaking Change werden übersprungen, sodass Versionen relativ selten sind.

Daneben gibt es die Version unstable, die dem aktuellen Entwicklungsstand folgt und Änderungen vor einem stabilen Release sichtbar macht. Bauen Sie darauf keine produktiven Integrationen auf.

Eine Version auswählen​

Zwei Wege, in dieser Reihenfolge der Priorität:

  1. URL-Pfad (empfohlen): Geben Sie die Version im Endpunkt an — …/backend/<subdomain>/api/2026-07/graphql. Das ist explizit, cache-freundlich und kopierbar.
  2. Request-Header: Senden Sie X-Api-Version: 2026-07 an den einfachen Endpunkt …/backend/<subdomain>/graphql.

Wenn Sie die Version weglassen — oder eine angeben, die unbekannt ist oder deren Sunset-Datum überschritten wurde —, wird die Anfrage von der ältesten noch unterstützten Version bedient, niemals von der neuesten. Sie werden nie stillschweigend auf einen Breaking Change umgestellt. Legen Sie für jede Integration, die Sie dauerhaft betreiben wollen, eine Version explizit fest.

Jede Antwort nennt die Version, die sie bedient hat, im Header X-Api-Version. So wissen Sie immer, welcher Vertrag geantwortet hat — und erkennen Abweichungen, falls Sie sich auf den Fallback verlassen haben.

Supportzeitraum​

Jede stabile Version wird mindestens 12 Monate unterstützt, mit mindestens 9 Monaten Überlappung mit der nächsten. In der Praxis sind jeweils zwei bis drei Versionen aktiv, was ein komfortables Zeitfenster für die Migration ergibt. Das Sunset-Datum einer Version wird an dem Tag veröffentlicht, an dem sie erscheint.

Was als Breaking Change gilt​

Innerhalb einer Version nehmen wir möglicherweise additive Änderungen vor, die Ihr Client tolerieren muss:

  • Hinzufügen eines neuen Typs, einer Query oder einer Mutation;
  • Hinzufügen eines optionalen Arguments zu einem bestehenden Feld;
  • Hinzufügen eines Felds zu einem Objekttyp;
  • Hinzufügen eines Werts zu einem Enum (gehen Sie also nie davon aus, dass ein Enum abgeschlossen ist).

Eine neue datierte Version ist echten Breaking Changes vorbehalten: Entfernen oder Umbenennen eines Felds oder Typs, Verschärfen der Nullability oder Ändern der Bedeutung eines Arguments oder eines Standardwerts. Diese treten niemals innerhalb einer bestehenden Version auf — die von Ihnen festgelegte Version behält ihr Verhalten bis zu ihrem Sunset-Datum.

Deprecations​

Deprecations werden auf zwei Wegen signalisiert, damit Sie davon erfahren, bevor etwas bricht:

  • Im Schema. Ein Feld, das ausläuft, wird mit @deprecated markiert, samt einer Begründung, die den Ersatz benennt. Introspection und das GraphQL Playground zeigen das jedem Client automatisch an.
  • In der Antwort. Wenn eine Anfrage tatsächlich ein veraltetes Feld auflöst, enthält die Antwort den Header X-Api-Deprecated-Reason (und einen passenden Eintrag extensions.deprecations), der die konkret berührten Deprecations nennt — so taucht eine Deprecation in Ihren Logs auf, sobald Sie darauf stoßen, ohne dass Sie danach suchen müssen.

Ein veraltetes Feld bleibt für einen veröffentlichten Mindestzeitraum erhalten, bevor es in einer späteren datierten Version entfernt wird.