API Deprecation in English: How to Communicate Breaking Changes to Developers (англійською)
English vocabulary and templates for API deprecation notices, migration guides, sunset timelines, and communicating breaking changes clearly to developer consumers.
Відмовитися від кінцевої точки API або вилучити функцію є технічним рішенням з комунікаційним викликом в його основі. Розробникам, які залежать від вашого API, слід розуміти, що змінюється, коли воно перестане працювати, що їм слід використовувати замість нього, і скільки зусиль буде потрібно для перенесення. Неправильне спілкування — неоднозначні графіки, нечіткі шляхи міграції, жаргонні повідомлення — створює розчарування і підриває довіру розробників. Для не англомовних носіїв, які підтримують публічні або внутрішні API, точна мова відмови є професійною відповідальністю.
Ключовий словник
Застаріла Процес позначення кінцевої точки, параметра або поведінки API як не рекомендованих, з визначеним планом їх вилучення у майбутньому. Застаріле не означає вилучено — це означає, що вилучення вже наближається.
“Кінечна точка /v1/users є застарілим з цього випуску. Він продовжить функціонувати до дати заходу сонця, але не повинен використовуватися в нових інтеграціях. ”
Все изменилось Зміна у API, яка призвела до того, що існуючий код клієнта перестав працювати, наприклад, вилучення кінцевої точки, зміна форми відповіді або зміна необхідних параметрів.
- “Вилучення поля
emailз об’ єкта відповіді користувача є зміною, що порушує правила. Клієнти, які посилаються на це поле, зазнають невдачі.”*
** Дата заходу сонця ** Вказано дату, після якої застарілі можливості буде остаточно вилучено і вони більше не будуть працювати.
“Аплітудний інтерфейс v1 має дату закінчення дії 1 вересня 2026 року. Після цієї дати всі v1 запити повертатимуть HTTP 410 Gone.”
Підручник з міграції Документація, яка пояснює крок за кроком, як перейти від застарілого API до його заміни.
“Посібник з міграції охоплює три кінцеві точки, які змінилися, і включає приклади коду до/після в Python і JavaScript.”
Кінець життя (EOL) Точка, на якій підтримка можливості, версії або API формально закінчується — більше немає виправлень помилок, латок безпеки або гарантій сумісності.
“Версія 1 API досягає кінця життя на 1 вересня 2026 року.”
** Версії API ** Практика підтримки декількох версій API одночасно, щоб дозволити споживачам мігрувати без обов’язкової синхронізації.
“Ми використовуємо версії, засновані на URL: кінцеві точки /v1/ і /v2/ будуть співіснувати під час перехідного періоду.”
** Повідомлення про знищення ** Формальна заява, яка повідомляє користувачів API про те, що функціональність буде вилучено, включаючи часову шкалу і шлях міграції.
“Ми надіслали повідомлення про зниження якості всім зареєстрованим користувачам API електронною поштою і додали заголовок Deprecation до всіх відповідей v1.”
Корисні фрази
** Обговорення застарілості: **
«Ми оголошуємо про знищення кінцевої точки
/v1/payments. Ця кінцева точка залишиться функціональною до 1 вересня 2026 року, після чого буде назавжди вилучена. Ми рекомендуємо перейти до кінцевої точки/v2/paymentsякомога швидше»
Пояснюю причину:
«Ми відкидаємо цю кінцеву точку, тому що формат відповіді v1 не підтримує багатовалютні транзакції, які потрібні для методів оплати, які ми додаємо в Q3. Конечна точка v2 була розроблена для підтримки цих випадків використання з самого початку»
** Опис змін: **
«Перша відмінність між v1 і v2 — це конверт відповіді. У v1, об’ єкт платежу повертається безпосередньо. У v2, він вбудований всередині
dataоб’єкта, відповідно до нашого стандартного формату відповіді по всіх кінцевих точках.”
Направлення до керівництва з переходу:
«Повна документація з міграції доступна на [docs link]. Довідник включає в себе порівняння форматів запитів і відповідей v1 і v2, приклад роботи для найпоширеніших випадків використання і часто задавані запитання для краєвих випадків
Відзначаючи вплив:
«Ми визнаємо, що будь-яка міграція вимагає інженерних зусиль, і ми намагалися мінімізувати обсяг необхідних змін. Якщо ви зіткнетеся з проблемами під час міграції або у вас є питання щодо вашого конкретного випадку використання, будь ласка, відкрийте квиток на підтримку і наша команда зв’язків з розробниками допоможе вам»
Поширені помилки
Встановлення неоднозначних часових ліній Фрази на кшталт “це скоро буде застарілим” або “ми плануємо вилучити це в найближчі місяці” не є корисними для споживачів API, яким потрібно планувати інженерну роботу. Завжди вказуйте конкретну дату заходу сонця: * « Цю кінцеву точку буде вилучено 1 вересня 2026 року. » * Якщо ви не готові до дати заходу сонця, вкажіть її у відповідному місці: * « Дата заходу сонця ще не визначена. Ми оголосимо про це не менше ніж за 90 днів до видалення. *
** Плутанина “застаріле” і “вилучено” ** Це різні стани з різними наслідками. Застаріла означає, що програма все ще працює, але її планується вилучити. Вилучений означає, що він більше не працює. Нерідні носії іноді використовують їх взаємно, викликаючи паніку або збої. Будь точним: *“Кінечна точка v1 застаріла — вона досі функціонує нормально. Його буде знято 1 вересня 2026 року. *
** Опускається шлях міграції ** Повідомлення про застарілий продукт без чіткої альтернативи є неповним і розчаруванням. Три питання, на які має відповісти кожне повідомлення про застарівання: що мені слід використовувати замість, що мені потрібно змінити в моєму коді, і коли мені потрібно це зробити. Якщо будь-який з цих трьох відсутній, повідомлення не є дієздатним.
Ясне повідомлення про зниження якості є формою поваги до розробників, які залежать від вашого API — зусилля, які ви вкладаєте у повідомлення і керівництво з міграції, безпосередньо зменшують вартість зміни для ваших користувачів.
Національні мови: англійська, не рідна для більшості населення
Ефективне повідомлення технічних змін є ключовим у будь-якому середовищі розробки програмного забезпечення, але коли розробники говорять англійською як другою мовою, виклик стає значно більшим. Це не просто передавання інформації; це забезпечення розуміння і мінімізація потенційних непорозумінь, які можуть призвести до затримок, розчарування і, врешті-решт, менш ефективного робочого процесу. Багато розробників, які вивчають професійну англійську, сильно покладаються на прямі переклади з їх рідних мов, які часто не мають важливих контекстних нюансів і ідіоматичних виразів, поширених у технічній документації або обговореннях перегляду коду. Цей розділ зосереджено на наданні цілейної підтримки для цієї групи, пропонуючи словниковий запас і фрази, які підходять для зменшення розриву і сприяння яснішому спілкуванню.
Однією з найбільших перешкод є розуміння термінології, пов’язаної з відмовою від використання - такі терміни, як “переломні зміни”, “захід сонця” і “міграція” можуть бути особливо важко зрозумілими без міцної основи в англійській технічній лексиці. Важливо вийти за рамки простого затвердження того, що кінцева точка API більше не працюватиме, і замість цього використовувати мову, яка чітко описує * чому * зміна необхідна і що розробникам потрібно зробити, щоб пристосуватися. Наприклад, замість того, щоб сказати «/old-endpoint API було виключено», більш корисною фразою буде: «Зважаючи на зміни вимог до інфраструктури, /old-endpoint API виводиться на пенсію. Ця зміна вводить зміну, яка знищує, оскільки вона залежить від застарілого протоколу. Ми створили посібник з міграції [посилання], який описує кроки, необхідні для оновлення вашої інтеграції за допомогою нового /new-endpoint.” Зауважте явне визнання «переломної зміни» і надання підтримки, яка може бути використана.
Розглянути повідомлення Slack під час перегляду коду. Рідний англомовний користувач може просто прокоментувати: «Цей код використовує застарілу кінцеву точку. Виправте це!», Однак, для не-рідного мовця, це може бути приголомшливо. Більш підтримуючий підхід буде таким: «Привіт [Ім’я розробника], я помітив, що ви використовуєте /old-endpoint в цьому файлі. Цей API буде вилучено з використання; нам потрібно оновити ваш код, щоб використовувати новий /new-endpoint. Будь ласка, ознайомтеся з посібником з переходу [посилання], де наведено інструкції та найкращі практики. Дайте мені знати, якщо у вас є якісь запитання - я радий допомогти! “Доданий контекст, ввічливе формулювання (“Привіт…”) і пропозиція допомоги значно покращує розуміння і зменшує потенційне тривога.
Нарешті, при написанні описів PR важливо бути надзвичайно ясним щодо впливу зміни. Замість неясного «Оновлена інтеграція API», використовуйте: «Цей запит на завантаження оновлює інтеграцію на стороні клієнта, щоб використовувати /new-endpoint після усунення /old-endpoint. Це означає, що розробники повинні оновити свій код, щоб врахувати параметри нової кінцевої точки і формат відповіді, як це описано у посібнику з міграції [посилання]. Було проведено ретельне тестування, щоб забезпечити безперебійну функціональність з оновленим API. Використання точного словника — « переривчасті зміни », « параметри », « формат відповіді » — у поєднанні з ясними інструкціями виключає неоднозначність і підготує розробників до успіху.