Версії та сумісність

API має одну основну версію, /v1, і вона лише розширюється. Інтеграція, написана сьогодні, працює й далі, коли з’являються нові функції: ніщо, на що вона спирається, не перейменовують, не видаляють і не наділяють новим значенням.

Номер версії

API має номер версії, як-от 1.62.0. Він змінюється з кожним випуском:

мінорний номер — коли щось додається: операція, поле, подія;
номер патча — коли виправлено опис або текст повідомлення й більше нічого не змінилося.

Версію, яку обслуговує адреса, можна будь-коли прочитати:

Де	Що
`GET /openapi.json`	`info.version` специфікації
Кожна подія стрічки подій і кожен вебхук	`api_version` — версія, схемі якої відповідає `data`

GET /v1/health теж має version, але це версія випуску Sursa, що обслуговує адресу, а не версія API.

Мінорну версію ви не вибираєте: кожен запит обслуговує поточна. Завдяки наведеним нижче правилам це безпечно.

Що може змінитися в /v1

Ці зміни можуть з’явитися в будь-якій мінорній версії. Пишіть інтеграцію так, щоб вони її не ламали:

Нові операції.
Нові необов’язкові параметри й поля запиту. Запити без них поводяться як раніше.
Нові поля у відповідях, об’єктах і подіях.
Нові значення переліків у відповідях, як-от новий статус картки чи новий тип події.
Нові коди помилок і нові заголовки відповідей.
Ліміти, що стають менш суворими: більша максимальна довжина, ширший діапазон.
Змінені формулювання текстів message у помилках і змінені описи.

До чого має бути готовий ваш код

Ігноруйте невідомі поля. Не завершуйтеся помилкою, коли у відповіді більше полів, ніж ви очікуєте, і не використовуйте суворих схем, що їх відхиляють.
Приймайте невідомі значення переліків. Будь-який перелік у відповіді може розширитися. Вважайте невідоме значення варіантом «інше», а не помилкою.
Пропускайте невідомі типи подій — і у вебхуках, і в потоках.
Обробляйте невідомі коди помилок за їхнім статусом HTTP: див. Помилки.
Не залежте від порядку полів в об’єктах JSON чи від точного тексту повідомлень.

Що ніколи не змінюється в /v1

Шлях, параметр, поле чи значення переліку ніколи не перейменовують і не видаляють.
Тип поля ніколи не змінюється, і поле ніколи не набуває нового значення, як-от нових одиниць вимірювання.
Запит, який приймається сьогодні, не відхилятимуть згодом.
Код статусу успішної відповіді лишається тим самим.
Коди помилок зберігають своє значення, а поле detail у відповідях із помилкою зберігає свою форму.
Типи подій ніколи не перейменовують і не видаляють, а їхні data лише отримують нові поля.

Несумісні зміни

Якщо колись знадобиться несумісна зміна, її випустять як нову основну версію, як-от /v2, поруч із /v1. /v1 працюватиме без змін, і обидві версії працюватимуть паралельно.

Коли маршрут збираються вивести з ужитку:

Його позначають deprecated у специфікації та вносять до журналу змін із датою, коли його вимкнуть.
Його відповіді містять заголовки Deprecation: true і Sunset: <date>.
Він працює щонайменше 180 днів після оголошення. Організації, чиї ключі API його використовують, отримують письмове повідомлення щонайменше за 90 днів.
Після дати припинення він ще 90 днів відповідає 410 з кодом api.gone.

Стежте за заголовком Deprecation у своїх журналах чи моніторингу: це найраніший сигнал, що маршрут, яким ви користуєтеся, зникне.

Як бути в курсі

Журнал змін цього порталу перелічує кожен випуск: що додано і що визнано застарілим. Перш ніж оновлювати власну інтеграцію, порівняйте її код із записами, що з’явилися після версії, під яку ви її писали.