Ga naar hoofdinhoud

API-versiebeheer

De publieke API gebruikt gedateerde versies, hetzelfde schema als Shopify, zodat de versie waarvoor u ontwikkelt niet onder u vandaan verschuift. Gedateerde versies vormen de grove grens voor breaking changes; binnen een versie blijft het schema uitsluitend aanvullend evolueren.

Versienamen​

Een versie heet YYYY-MM, waarbij de maand het begin van een kwartaal is: 2026-01, 2026-04, 2026-07, 2026-10. Een nieuwe gedateerde versie verschijnt alleen wanneer er een breaking change is — kwartalen zonder breaking change worden overgeslagen, dus versies zijn relatief zeldzaam.

Er is ook een unstable-versie die de nieuwste ontwikkelingen volgt, om wijzigingen vooruit te bekijken vóór een stabiele release. Bouw daar geen productie-integraties op.

Een versie kiezen​

Twee manieren, in volgorde van voorrang:

  1. URL-pad (aanbevolen): zet de versie in het eindpunt — …/backend/<subdomain>/api/2026-07/graphql. Dat is expliciet, cachevriendelijk en makkelijk te kopiëren.
  2. Requestheader: stuur X-Api-Version: 2026-07 naar het kale eindpunt …/backend/<subdomain>/graphql.

Als u de versie weglaat — of er een noemt die onbekend is of waarvan de einddatum verstreken is — wordt de aanvraag afgehandeld door de oudste nog ondersteunde versie, nooit de nieuwste. U wordt nooit stilzwijgend op een breaking change gezet. Zet voor elke integratie die u wilt blijven onderhouden expliciet een versie vast.

Elk antwoord vermeldt de versie die het afhandelde in een X-Api-Version-header, zodat u altijd weet welk contract antwoordde — en afwijkingen opmerkt als u op het standaardgedrag vertrouwde.

Ondersteuningsperiode​

Elke stabiele versie wordt minstens 12 maanden ondersteund, met minstens 9 maanden overlap met de volgende. In de praktijk zijn er steeds twee tot drie versies actief, wat een comfortabel venster geeft om te migreren. De einddatum van een versie wordt gepubliceerd op de dag dat die uitkomt.

Wat telt als breaking change​

Binnen één versie kunnen we aanvullende wijzigingen doorvoeren, en uw client moet die verdragen:

  • een nieuw type, een query of een mutatie toevoegen;
  • een optioneel argument aan een bestaand veld toevoegen;
  • een veld aan een objecttype toevoegen;
  • een waarde aan een enum toevoegen (ga er dus nooit van uit dat een enum gesloten is).

Een nieuwe gedateerde versie is voorbehouden aan echt brekende wijzigingen: een veld of type verwijderen of hernoemen, nullability aanscherpen, of de betekenis van een argument of standaardwaarde wijzigen. Die gebeuren nooit binnen een bestaande versie — de versie die u hebt vastgezet behoudt haar gedrag tot haar einddatum.

Deprecaties​

Deprecaties worden op twee manieren gesignaleerd, zodat u ervan hoort voordat er iets breekt:

  • In het schema. Een veld dat wordt uitgefaseerd, is gemarkeerd met @deprecated en een reden die de vervanger noemt. Introspectie en de GraphQL Playground tonen dit automatisch aan elke client.
  • In het antwoord. Wanneer een aanvraag daadwerkelijk een verouderd veld oplost, bevat het antwoord de header X-Api-Deprecated-Reason (en een bijbehorende extensions.deprecations-vermelding) met de specifieke deprecaties die zijn geraakt — zo verschijnt een deprecatie in uw logs op het moment dat u er een tegenkomt, zonder dat u ernaar hoeft te zoeken.

Een verouderd veld blijft een gepubliceerde minimumperiode bestaan voordat het in een latere gedateerde versie wordt verwijderd.