API Deprecation English: Communicating Breaking Changes to Developers (англійською)

Introduction

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

Закінчення, закінчення, закінчення

Три терміни описують різні стадії виведення API з обігу:

• ** застаріла ** — функція все ще працює, але більше не рекомендується і буде вилучено у майбутній версії; « ця кінцева точка застаріла з версії 2. 4 »
• ** sunset ** — дата, після якої застаріла функціональність більше не буде доступною; « API версії 1 закінчиться 31 грудня 2026 року »
• ** кінець життя (EOL) ** — момент, коли функція більше не підтримується; « API v1 досяг кінця життя і тепер повертає 410 Gone для всіх викликів »

Різниця має значення: застарілий API все ще працює. API sunsetted або EOL не має. У повідомленнях про застарівання ви побачите: « Кінечна точка /v1/users застаріла. Він продовжить функціонувати до закінчення часу [дата], після чого поверне HTTP 410.”

HTTP 410 (Видалено) — правильний код стану для ресурсу, який було назавжди вилучено. Інженери іноді плутають його з 404 (Не знайдено). Використання правильного коду стану у вашій реалізації виключення з обігу показує вашу майстерність.

Зміни в ній не відбуваються

Не всі зміни однакові. Словник:

• ** breaking change ** — зміна, яка вимагає від розробників оновлення їх коду, щоб уникнути помилок; вилучення поля, зміна типу відповіді або вилучення кінцевої точки
• ** зміна, яка не потребує оновлення (зворотньо сумісна зміна) ** — зміна, яка не потребує оновлення клієнта; додавання нового необов’ язкового поля, додавання нової кінцевої точки
• ** додавання зміни ** — особливий тип непереривної зміни, яка лише додає нові речі; « додавання поля createdAt до відповіді є додаванням, зворотньо сумісною зміною »
• ** семантичний контроль версій ** — контроль версій, який повідомляє про ступінь тяжкості змін: основні версії містять зміни, які знищують, дрібні версії додають можливості, версії з латками виправляють вади

У повідомленнях про зниження якості, ви повинні бути чіткими: “Це зміна, що перервала. Клієнти, які не перейдуть до наступної дати, отримають помилки. Недооцінка впливу — це поширена помилка.

Міграційні процеси

** Посібник з міграції ** це документ, який допомагає розробникам перейти зі старого API на новий. Словник щодо перенесення:

• «Міграція з v1 до v2» — дії, які повинні зробити розробники
• «Крок за кроком міграція» — керівництво, яке розбиває процес на пронумеровані кроки
• «Ми надаємо скрипт міграції» — інструменти для автоматизації частин переходу
• «Мінімальна реальна міграція» — найменша зміна, необхідна для уникнення помилок; «мінімальна реальна міграція — замінити /v1/users на /v2/accounts»
• «Вікно міграції» — період між забороною і заходом сонця, протягом якого розробники можуть мігрувати; «ми надаємо 12-місячне вікно міграції»

Фраза «вікно міграції» сигналізує, скільки часу мають розробники. Довші вікна більш відповідають розкладам розробників. Ви почуєте, як команди обговорюють: « Шість місяців — це занадто короткий термін для клієнтів з великими підприємствами, які мають довгі цикли випуску »

Розповідь про розчарування

Як ви повідомляєте про відмову від використання так само важливо, як і сама технічна зміна. Стандартні правила:

• ** Deprecation заголовок** — заголовок HTTP, який сигналізує про застарілу кінцеву точку в відповіді; « ми додаємо заголовок Deprecation з датою до всіх відповідей v1 »
• ** Sunset заголовок** — заголовок HTTP, який повідомляє дату заходу сонця у відповіді
• ** changelog ** — документ, у якому записано всі зміни; « ми оголошуємо про застарілі версії спочатку у журналі змін »
• ** оголошення розробника ** — повідомлення у блогу або електронна пошта для зареєстрованих розробників; « ми надсилаємо оголошення розробника за 90 днів до кожної дати затемнення »
• «Ми даємо попереднє попередження» — повідомляємо про зміни рано; «ми даємо принаймні 6 місяців попередження про будь-які зміни»

Ключовий словник

Term	Definition
deprecated	A feature that still works but is scheduled for removal
sunset date	The date after which a deprecated feature will be removed
end of life	The moment when a feature is permanently removed
breaking change	A change that requires developers to update their code
additive change	A backwards-compatible change that only adds new functionality
migration guide	Documentation explaining how to move from old to new API
migration window	The time between deprecation and sunset for developers to migrate
semantic versioning	A versioning scheme where major versions signal breaking changes
Deprecation header	An HTTP response header signalling that the endpoint is deprecated
advance notice	Warning given to developers before a breaking change takes effect

Практичні поради

1. ** Написати повідомлення про виключення з використання для вигаданої кінцевої точки. ** Вправитись у структурі повідомлення: оголосити про виключення з використання, вказати дату закінчення, посилання на довідник з перенесення, а також вказати контакт для запитів. Використовуйте словник: “Кінечна точка /v1/products є застарілим з сьогоднішнього дня. Закінчиться 1 березня 2027 року. Будь ласка, мігруйте до /v2/products за допомогою нашого посібника з міграції»

2. ** Вчимося відрізняти пошкодження від не пошкодження. ** Для кожної зміни API, яку ви вносите, вправляйтеся у запитанні: « Чи буде клієнт, який не змінив свій код, працювати належним чином? » Якщо так, це не пошкодження. Якщо ні, це пошкодження зміни і вимагає процесу виведення з ладу.

3. ** Використовуйте семантичну мову версій правильно. ** « Ми переносимо головну версію, оскільки цей випуск містить зміни, які знищують» — це правильний спосіб описати збільшення головної версії. Вправлятися у використанні слів « major », « minor » і « patch » з їх правильним семантичним значенням.

4. ** Прочитайте оголошення про знищення API від Stripe, Twilio або GitHub. ** Ці компанії відомі чудовими зв’ язками з розробниками. Їхні повідомлення про застарівання є моделями ясності, попереднього попередження і керівництва з міграції.

Conclusion

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