Перейти до основного вмісту

Версіонування API

Публічний API використовує датовані версії — ту саму схему, що й Shopify, — тож версія, під яку ви розробляєте, не зміниться у вас під ногами. Датовані версії є грубою межею для несумісних змін; у межах однієї версії схема продовжує розвиватися лише шляхом додавання.

Назви версій​

Версія має назву YYYY-MM, де місяць — це початок кварталу: 2026-01, 2026-04, 2026-07, 2026-10. Нова датована версія випускається лише тоді, коли є несумісна зміна — квартали без несумісних змін пропускаються, тому версії з'являються відносно рідко.

Існує також версія unstable, яка відображає найновіші напрацювання та дозволяє переглядати зміни до їх стабільного випуску. Не створюйте на її основі промислові інтеграції.

Вибір версії​

Є два способи, у порядку пріоритету:

  1. Шлях в URL (рекомендовано): вкажіть версію в ендпоінті — …/backend/<subdomain>/api/2026-07/graphql. Це явно, зручно для кешування та легко копіюється.
  2. Заголовок запиту: надішліть X-Api-Version: 2026-07 до базового ендпоінта …/backend/<subdomain>/graphql.

Якщо ви не вказали версію — або вказали невідому чи таку, підтримку якої вже припинено, — запит обслуговує найстаріша з версій, що ще підтримуються, а не найновіша. Вас ніколи не переводять на несумісну зміну непомітно. Явно закріплюйте версію для будь-якої інтеграції, яку плануєте підтримувати надалі.

Кожна відповідь повідомляє версію, яка її обслужила, у заголовку X-Api-Version — тож ви завжди знаєте, який саме контракт відповів, і можете виявити розбіжність, якщо покладалися на автоматичний вибір версії.

Період підтримки​

Кожна стабільна версія підтримується щонайменше 12 місяців, з перекриттям щонайменше 9 місяців із наступною версією. На практиці одночасно живими є дві-три версії, що дає комфортний запас часу для міграції. Дата припинення підтримки версії публікується в день її випуску.

Що вважається несумісною зміною​

У межах однієї версії ми можемо вносити зміни шляхом додавання, і ваш клієнт має бути до них толерантним:

  • додавання нового типу, запиту або мутації;
  • додавання необов'язкового аргументу до наявного поля;
  • додавання поля до об'єктного типу;
  • додавання значення до переліку enum (тому ніколи не вважайте enum закритим).

Нова датована версія призначена лише для справді несумісних змін: видалення чи перейменування поля або типу, посилення вимог щодо nullability, зміна значення аргументу чи значення за замовчуванням. Такі зміни ніколи не відбуваються всередині наявної версії — закріплена вами версія зберігає свою поведінку до дати припинення підтримки.

Застарілі елементи​

Про застарілі елементи повідомляється двома способами, тож ви дізнаєтеся про них ще до того, як щось перестане працювати:

  • У схемі. Поле, яке виводиться з обігу, позначається @deprecated із причиною, що називає його заміну. Інтроспекція та GraphQL Playground автоматично показують це кожному клієнту.
  • У відповіді. Коли запит справді звертається до застарілого поля, відповідь містить заголовок X-Api-Deprecated-Reason (і відповідний запис extensions.deprecations), який називає конкретні застарілі елементи, яких торкнувся запит, — тож застарілий елемент з'явиться у ваших логах одразу, щойно ви його використаєте, без потреби шукати його самостійно.

Застаріле поле зберігається протягом опублікованого мінімального періоду, перш ніж його буде видалено в одній із наступних датованих версій.