Hoppa till huvudinnehåll

API-versionshantering

Det publika API:et använder daterade versioner, samma upplägg som Shopify, så att den version du utvecklar mot inte förändras under fötterna på dig. Daterade versioner är den grova gränsen för brytande ändringar; inom en version fortsätter schemat att utvecklas enbart genom tillägg.

Versionsnamn​

En version heter YYYY-MM, där månaden är början på ett kvartal: 2026-01, 2026-04, 2026-07, 2026-10. En ny daterad version skapas bara när det finns en brytande ändring — kvartal utan brytande ändringar hoppas över, så versioner är relativt sällsynta.

Det finns också en unstable-version som följer den senaste utvecklingen, så att du kan se ändringar i förväg innan en stabil release. Bygg inte produktionsintegrationer på den.

Välja version​

Två sätt, i prioritetsordning:

  1. URL-sökväg (rekommenderas): lägg in versionen i endpunkten — …/backend/<subdomain>/api/2026-07/graphql. Det är tydligt, cachevänligt och lätt att kopiera.
  2. Begärandehuvud: skicka X-Api-Version: 2026-07 till den rena endpunkten …/backend/<subdomain>/graphql.

Om du utelämnar versionen — eller anger en som är okänd eller vars supporttid gått ut — hanteras begäran av den äldsta version som fortfarande stöds, aldrig den nyaste. Du flyttas aldrig tyst över till en brytande ändring. Lås fast en version uttryckligen för varje integration du tänker underhålla.

Varje svar anger den version som hanterade det i huvudet X-Api-Version, så du vet alltid vilket kontrakt som svarade — och upptäcker avvikelser om du förlitat dig på standardbeteendet.

Supportperiod​

Varje stabil version stöds i minst 12 månader, med minst 9 månaders överlappning med nästa. I praktiken är två till tre versioner igång samtidigt, vilket ger ett bekvämt fönster att migrera i. En versions utfasningsdatum publiceras samma dag som versionen släpps.

Vad som räknas som brytande ändring​

Inom en och samma version kan vi göra tillägg, och din klient måste tåla dem:

  • lägga till en ny typ, fråga eller mutation;
  • lägga till ett valfritt argument på ett befintligt fält;
  • lägga till ett fält på en objekttyp;
  • lägga till ett värde i en enum (utgå därför aldrig från att en enum är sluten).

En ny daterad version är reserverad för verkligt brytande ändringar: att ta bort eller byta namn på ett fält eller en typ, att skärpa nullbarhet, eller att ändra innebörden av ett argument eller ett standardvärde. Sådant sker aldrig inuti en befintlig version — den version du låst fast behåller sitt beteende fram till sitt utfasningsdatum.

Utfasningar​

Utfasningar aviseras på två sätt, så att du får veta innan något går sönder:

  • I schemat. Ett fält som fasas ut markeras med @deprecated och en motivering som namnger ersättaren. Introspektion och GraphQL Playground visar detta automatiskt för varje klient.
  • I svaret. När en begäran faktiskt löser upp ett utfasat fält bär svaret huvudet X-Api-Deprecated-Reason (och en motsvarande extensions.deprecations-post) som namnger just de utfasningar den berörde — en utfasning dyker alltså upp i dina loggar i samma stund du stöter på den, utan att du behöver leta.

Ett utfasat fält behålls under en publicerad minimiperiod innan det tas bort i en senare daterad version.