Gå til hovedinnhold

API-versjonering

Det offentlige API-et bruker daterte versjoner, samme opplegg som Shopify, slik at versjonen du utvikler mot ikke endrer seg under føttene dine. Daterte versjoner er den grove grensen for bruddendringer; innenfor en versjon fortsetter skjemaet å utvikle seg kun ved tillegg.

Versjonsnavn​

En versjon heter YYYY-MM, der måneden er starten på et kvartal: 2026-01, 2026-04, 2026-07, 2026-10. En ny datert versjon lages bare når det finnes en bruddendring — kvartaler uten bruddendringer hoppes over, så versjoner er forholdsvis sjeldne.

Det finnes også en unstable-versjon som følger siste utvikling, slik at du kan se endringer an før en stabil utgivelse. Ikke bygg produksjonsintegrasjoner på den.

Velge versjon​

To måter, i prioritert rekkefølge:

  1. URL-sti (anbefalt): legg versjonen inn i endepunktet — …/backend/<subdomain>/api/2026-07/graphql. Det er eksplisitt, cachevennlig og lett å kopiere.
  2. Forespørselshode: send X-Api-Version: 2026-07 til det rene endepunktet …/backend/<subdomain>/graphql.

Hvis du utelater versjonen — eller oppgir en som er ukjent eller er ute av støtte — betjenes forespørselen av den eldste versjonen som fortsatt støttes, aldri den nyeste. Du blir aldri stilltiende flyttet over på en bruddendring. Lås versjonen eksplisitt for enhver integrasjon du har tenkt å vedlikeholde.

Hvert svar oppgir versjonen som betjente det i et X-Api-Version-hode, slik at du alltid vet hvilken kontrakt som svarte — og oppdager avvik hvis du har lent deg på standardoppførselen.

Støtteperiode​

Hver stabile versjon støttes i minst 12 måneder, med minst 9 måneders overlapp med den neste. I praksis er to til tre versjoner i drift til enhver tid, noe som gir et romslig vindu til å migrere i. Utfasingsdatoen for en versjon publiseres den dagen den kommer.

Hva som regnes som bruddendring​

Innenfor én versjon kan vi gjøre tilleggsendringer, og klienten din må tåle dem:

  • legge til en ny type, spørring eller mutasjon;
  • legge til et valgfritt argument på et eksisterende felt;
  • legge til et felt på en objekttype;
  • legge til en verdi i en enum (anta derfor aldri at en enum er lukket).

En ny datert versjon er forbeholdt reelle bruddendringer: å fjerne eller gi nytt navn til et felt eller en type, å stramme inn nullbarhet, eller å endre betydningen av et argument eller en standardverdi. Slikt skjer aldri inne i en eksisterende versjon — versjonen du har låst, beholder oppførselen sin frem til utfasingsdatoen.

Utfasinger​

Utfasinger varsles på to måter, slik at du får vite om dem før noe slutter å virke:

  • I skjemaet. Et felt som fases ut, merkes med @deprecated og en begrunnelse som nevner erstatningen. Introspeksjon og GraphQL Playground viser dette automatisk til alle klienter.
  • I svaret. Når en forespørsel faktisk løser opp et utdatert felt, får svaret hodet X-Api-Deprecated-Reason (og en tilsvarende extensions.deprecations-oppføring) som nevner nettopp de utfasingene den berørte — en utfasing dukker altså opp i loggene dine i samme øyeblikk du treffer på den, uten at du må lete.

Et utdatert felt beholdes i en publisert minsteperiode før det fjernes i en senere datert versjon.