Hop til hovedindhold

API-versionering

Det offentlige API bruger daterede versioner, samme princip som Shopify, så den version, du udvikler mod, ikke ændrer sig under dig. Daterede versioner er den grove grænse for brydende ændringer; inden for en version udvikler skemaet sig fortsat kun ved tilføjelser.

Versionsnavne​

En version hedder YYYY-MM, hvor måneden er starten på et kvartal: 2026-01, 2026-04, 2026-07, 2026-10. En ny dateret version udsendes kun, når der er en brydende ændring — kvartaler uden brydende ændringer springes over, så versioner er forholdsvis sjældne.

Der findes også en unstable-version, der følger den nyeste udvikling, så du kan se ændringer an inden en stabil udgivelse. Byg ikke produktionsintegrationer på den.

Valg af version​

To måder, i prioriteret rækkefølge:

  1. URL-sti (anbefales): læg versionen ind i endpointet — …/backend/<subdomain>/api/2026-07/graphql. Det er eksplicit, cachevenligt og let at kopiere.
  2. Anmodningsheader: send X-Api-Version: 2026-07 til det rene endpoint …/backend/<subdomain>/graphql.

Hvis du udelader versionen — eller angiver en, der er ukendt eller er ude af support — betjenes anmodningen af den ældste stadig understøttede version, aldrig den nyeste. Du bliver aldrig stiltiende flyttet over på en brydende ændring. Fastlås versionen eksplicit i enhver integration, du agter at vedligeholde.

Hvert svar oplyser den version, der betjente det, i en X-Api-Version-header, så du altid ved, hvilken kontrakt der svarede — og opdager afvigelser, hvis du har lænet dig op ad standardadfærden.

Supportperiode​

Hver stabil version understøttes i mindst 12 måneder, med mindst 9 måneders overlap til den næste. I praksis er der til enhver tid to til tre versioner i drift, hvilket giver et behageligt vindue til at migrere i. En versions udfasningsdato offentliggøres den dag, den udkommer.

Hvad tæller som en brydende ændring​

Inden for én version kan vi foretage tilføjende ændringer, og din klient skal kunne tåle dem:

  • tilføje en ny type, forespørgsel eller mutation;
  • tilføje et valgfrit argument til et eksisterende felt;
  • tilføje et felt til en objekttype;
  • tilføje en værdi til en enum (gå derfor aldrig ud fra, at en enum er lukket).

En ny dateret version er forbeholdt reelt brydende ændringer: at fjerne eller omdøbe et felt eller en type, at stramme nullability, eller at ændre betydningen af et argument eller en standardværdi. Dem sker der aldrig inden i en eksisterende version — den version, du har fastlåst, beholder sin adfærd frem til sin udfasningsdato.

Udfasninger​

Udfasninger varsles på to måder, så du hører om dem, før noget går i stykker:

  • I skemaet. Et felt, der udgår, er markeret med @deprecated og en begrundelse, der nævner afløseren. Introspektion og GraphQL Playground viser dette automatisk til enhver klient.
  • I svaret. Når en anmodning rent faktisk opløser et forældet felt, indeholder svaret headeren X-Api-Deprecated-Reason (og en tilsvarende extensions.deprecations-post), som nævner netop de udfasninger, den berørte — en udfasning dukker altså op i dine logs i samme øjeblik, du rammer den, uden at du skal lede efter den.

Et forældet felt bevares i en offentliggjort minimumsperiode, før det fjernes i en senere dateret version.