Wersjonowanie API

Publiczne API używa wersji datowanych — tego samego schematu co Shopify — dzięki czemu wersja, pod którą tworzysz, nie zmieni się pod tobą. Wersje datowane wyznaczają zgrubną granicę dla zmian niezgodnych wstecz; wewnątrz jednej wersji schemat nadal rozwija się wyłącznie przez dodawanie.

Nazwy wersji

Wersja nazywa się YYYY-MM, gdzie miesiąc to początek kwartału: 2026-01, 2026-04, 2026-07, 2026-10. Nowa wersja datowana powstaje tylko wtedy, gdy pojawia się zmiana niezgodna wstecz — kwartały bez takich zmian są pomijane, więc wersje są stosunkowo rzadkie.

Istnieje także wersja unstable, która podąża za najnowszym stanem prac i pozwala podejrzeć zmiany przed stabilnym wydaniem. Nie buduj na niej integracji produkcyjnych.

Wybór wersji

Dwa sposoby, w kolejności pierwszeństwa:

1. Ścieżka w adresie URL (zalecane): umieść wersję w punkcie końcowym — …/backend/<subdomain>/api/2026-07/graphql. Jest to jednoznaczne, przyjazne dla pamięci podręcznej i łatwe do skopiowania.
2. Nagłówek żądania: wyślij X-Api-Version: 2026-07 na zwykły punkt końcowy …/backend/<subdomain>/graphql.

Jeśli pominiesz wersję — albo podasz nieznaną lub taką, której wsparcie już wygasło — żądanie obsłuży najstarsza wciąż wspierana wersja, nigdy najnowsza. Nigdy nie zostaniesz po cichu przeniesiony na zmianę niezgodną wstecz. Dla każdej integracji, którą zamierzasz utrzymywać, przypnij wersję jawnie.

Każda odpowiedź podaje wersję, która ją obsłużyła, w nagłówku X-Api-Version — zawsze wiesz więc, który kontrakt odpowiedział, i wykryjesz rozjazd, jeśli polegałeś na zachowaniu domyślnym.

Okres wsparcia

Każda stabilna wersja jest wspierana przez co najmniej 12 miesięcy, z co najmniej 9 miesiącami zachodzenia na kolejną. W praktyce w danym momencie aktywne są dwie lub trzy wersje, co daje wygodne okno na migrację. Data zakończenia wsparcia wersji jest publikowana w dniu jej wydania.

Co liczy się jako zmiana niezgodna wstecz

W obrębie jednej wersji możemy wprowadzać zmiany przez dodawanie, a Twój klient musi je tolerować:

• dodanie nowego typu, zapytania lub mutacji;
• dodanie opcjonalnego argumentu do istniejącego pola;
• dodanie pola do typu obiektowego;
• dodanie wartości do wyliczenia enum (nigdy więc nie zakładaj, że enum jest zamknięty).

Nowa wersja datowana jest zarezerwowana dla prawdziwie niezgodnych zmian: usunięcia lub zmiany nazwy pola albo typu, zaostrzenia wymagań co do wartości pustych, albo zmiany znaczenia argumentu lub wartości domyślnej. Takie zmiany nigdy nie zachodzą wewnątrz istniejącej wersji — przypięta przez Ciebie wersja zachowuje swoje zachowanie aż do zakończenia wsparcia.

Wycofania

Wycofania sygnalizowane są na dwa sposoby, abyś dowiedział się o nich, zanim cokolwiek przestanie działać:

• W schemacie. Wycofywane pole jest oznaczone @deprecated wraz z uzasadnieniem wskazującym zamiennik. Introspekcja i GraphQL Playground pokazują to automatycznie każdemu klientowi.
• W odpowiedzi. Gdy żądanie faktycznie rozwiązuje wycofane pole, odpowiedź zawiera nagłówek X-Api-Deprecated-Reason (oraz odpowiadający mu wpis extensions.deprecations) wskazujący konkretne wycofania, których dotyczyło — wycofanie pojawia się więc w Twoich logach w chwili, gdy je napotkasz, bez konieczności szukania.

Wycofane pole jest utrzymywane przez opublikowany minimalny okres, zanim zostanie usunięte w późniejszej wersji datowanej.