Verzování API

Veřejné API používá datované verze, stejné schéma jako Shopify, takže se verze, nad kterou vyvíjíte, nezmění pod rukama. Datované verze jsou hrubou hranicí pro nekompatibilní změny; uvnitř jedné verze se schéma dál rozvíjí pouze přidáváním.

Názvy verzí

Verze se jmenuje YYYY-MM, kde měsíc je začátek čtvrtletí: 2026-01, 2026-04, 2026-07, 2026-10. Nová datovaná verze vzniká jen tehdy, když dojde k nekompatibilní změně — čtvrtletí bez takové změny se přeskakují, takže verzí je poměrně málo.

Existuje také verze unstable, která sleduje nejnovější stav vývoje a umožňuje si prohlédnout změny ještě před stabilním vydáním. Nestavte na ní produkční integrace.

Výběr verze

Dvě možnosti, v pořadí podle přednosti:

1. Cesta v URL (doporučeno): uveďte verzi v koncovém bodě — …/backend/<subdomain>/api/2026-07/graphql. Je to explicitní, přívětivé ke keši a snadno se to kopíruje.
2. Hlavička požadavku: pošlete X-Api-Version: 2026-07 na prostý koncový bod …/backend/<subdomain>/graphql.

Pokud verzi vynecháte — nebo uvedete neznámou či takovou, jejíž podpora už skončila — požadavek obslouží nejstarší dosud podporovaná verze, nikdy ne ta nejnovější. Nikdy nejste potichu převedeni na nekompatibilní změnu. U každé integrace, kterou hodláte udržovat, si verzi zafixujte výslovně.

Každá odpověď uvádí verzi, která ji obsloužila, v hlavičce X-Api-Version — vždy tak víte, která smlouva odpověděla, a odhalíte odchylku, pokud jste spoléhali na výchozí chování.

Doba podpory

Každá stabilní verze je podporována nejméně 12 měsíců, s překryvem nejméně 9 měsíců s následující verzí. V praxi jsou v každém okamžiku živé dvě až tři verze, což dává pohodlný prostor na migraci. Datum ukončení podpory verze se zveřejňuje v den jejího vydání.

Co se počítá jako nekompatibilní změna

V rámci jedné verze můžeme provádět změny přidáním a váš klient je musí snést:

• přidání nového typu, dotazu nebo mutace;
• přidání volitelného argumentu ke stávajícímu poli;
• přidání pole do objektového typu;
• přidání hodnoty do výčtu (nikdy tedy nepředpokládejte, že je výčet uzavřený).

Nová datovaná verze je vyhrazena skutečně nekompatibilním změnám: odstranění nebo přejmenování pole či typu, zpřísnění nullability, nebo změna významu argumentu či výchozí hodnoty. Ty se uvnitř existující verze nikdy nedějí — verze, kterou jste si zafixovali, si zachová své chování až do konce podpory.

Ukončení podpory prvků

Ukončení podpory se oznamuje dvěma způsoby, abyste se o něm dozvěděli dřív, než něco přestane fungovat:

• Ve schématu. Pole, které se vyřazuje, je označeno @deprecated s odůvodněním, jež pojmenuje jeho náhradu. Introspekce a GraphQL Playground to automaticky ukážou každému klientovi.
• V odpovědi. Když požadavek skutečně vyhodnotí zastaralé pole, odpověď nese hlavičku X-Api-Deprecated-Reason (a odpovídající položku extensions.deprecations) s konkrétními zastaralými prvky, kterých se dotkl — zastaralost se tak objeví ve vašich logech ve chvíli, kdy na ni narazíte, aniž byste ji museli hledat.

Zastaralé pole se udržuje po zveřejněnou minimální dobu, než je odstraněno v některé pozdější datované verzi.