Як обговорювати API Deprecation з зовнішніми розробниками англійською мовою
Вивчіть англійську фразу для повідомлення зовнішнім розробникам про припинення використання API, починаючи з початкового оголошення і закінчуючи обробкою зворотнього звіту.
Відкидання API, від якого залежать зовнішні команди, є іншою проблемою комунікації, ніж відкидання чогось внутрішнього — ви не контролюєте їх розклад випуску, часто не можете побачити їх використання безпосередньо, а нечітка хронологія може пошкодити інтеграції, про існування яких ви навіть не знаєте. Цей підручник описує формулювання, яке дотримується цих обмежень.
Ключовий словник
** Повідомлення про застарівання ** — офіційне повідомлення з датою, що підтримка API (або певної версії, кінцевої точки або поля) буде припинено у визначену дату у майбутньому, що надасть зовнішнім користувачам попереднє попередження про необхідність переходу на нову версію. “Ми публікуємо повідомлення про зниження цінності для кінцевої точки v1 сьогодні, з твердою датою закінчення дії через шість місяців — це дає кожному партнеру з інтеграції справжнє вікно для міграції, а не переборювання.”
** Дата закінчення дії ** — конкретна дата, після якої застарілий API припинить функціонувати повністю, відмінна від дати повідомлення про застарілий API, і, ідеально, оголошена з достатнім часом для того, щоб зовнішні команди могли планувати навколо неї. “Дата закінчення — 1 березня, а не день, коли ми оголосили про це — це чотиримісячне вікно, спеціально для того, щоб команди з довшими циклами випуску мали реалістичний шлях для міграції, перш ніж це насправді зламає.”
** Шлях міграції ** — конкретні, задокументовані кроки, які слід виконати зовнішньому розробнику для переходу від застарілого API до його заміни, ідеально, якщо цей документ міститиме приклади коду і відображення поведінки старого і нового API. “Одного лише повідомлення про зниження якості недостатньо — нам потрібно опублікувати фактичний шлях міграції, з порівнянням старих і нових форматів запитів, або ми просто кажемо людям, що щось не працює, не кажучи їм, що робити з цим.”
** Період відстрочки ** — вікно після закінчення терміну дії, протягом якого застарілі API технічно все ще працюють, часто з заголовком попередження або зменшеною підтримкою, надаючи командам, які пропустили початковий термін, останній буфер перед критичним збоєм. “Ми додаємо двотижневий період відстрочки після офіційної дати закінчення — кінцева точка буде продовжувати працювати, але повертатиме заголовок попередження про застарівання, спеціально для того, щоб захопити будь-яку інтеграцію, про яку ми не знали до її раптової невдачі.”
Звичайні фрази
- Чи ми опублікували попередження про застарівання з твердою датою затемнення ще?»
- Чи є документований шлях міграції, чи ми просто кажемо людям, що він зникає?»
- «Скільки часу ми даємо до дати заходу сонця?»
- Чи варто нам додати період відстрочки в разі, якщо є інтеграції, які ми не маємо видимості?»
- Як ми попереджуємо існуючих споживачів — електронною поштою, changelog, заголовками відповідей API, або всіма трьома?»
Приклади висловлювань
Запис початкового повідомлення про застарівання:
*“Ми відмовляємося від кінцевої точки v1 /search через шість місяців з сьогоднішнього дня. Він продовжить працювати до закінчення терміну дії, після чого запити повертатимуть 410 Gone. Повна документація щодо міграції, включаючи порівняння запитів/відповідей з v2, наведена нижче. *
Відповідь на запит партнера про більше часу: “Ми чули, що шість місяців недостатньо, враховуючи ваш цикл випуску — ми можемо продовжити дату закінчення на додаткові два місяці, але нам потрібна дата переходу з вашої сторони, щоб ми могли запланувати власну роботу з видаленням навколо цього.”
Пояснюючи рішення внутрішньо інженерії: “Ми додаємо двотижневий період з заголовками попереджень після офіційної дати закінчення, не тому, що ми продовжуємо справжній термін, а тому, що ми знаємо, що є інтеграції від менших партнерів, з якими ми не маємо прямого контакту, і жорстке відключення з нульовим буфером ризикує пошкодити їх без попередження.”
Професійні поради
- Завжди поєднуйте повідомлення про знищення з явною датою закінчення, а не просто «це буде скоро вилучено» — нечітка хронологія не дає зовнішнім командам нічого конкретного, щоб планувати міграцію.
- Опублікуйте ** шлях міграції ** разом з повідомленням про знищення, а не після нього — оголошення про те, що щось зникає без повідомлення про те, що робити, створює тривогу, не даючи нікому можливості зробити наступний крок.
- Встановіть дату завершення роботи на основі реальних зовнішніх циклів випуску, а не вашого власного внутрішнього плану — зовнішні розробники часто працюють повільніше, ніж внутрішня команда, а нереалістичні терміни просто призведуть до відсилання і пропущених міграцій.
- Розгляньте ** період відстрочки ** з видимими попередженнями (не мовчазна помилка) спеціально для зовнішніх API, де ви, ймовірно, маєте неповну видимість у кожному споживачі — це ловить інтеграції, про існування яких ви не знали до того, як вони порушили виробництво.
Практичні вправи
- Написати повідомлення про знищення гіпотетичної кінцевої точки API, включаючи дату закінчення дії і місце, де можна знайти шлях міграції.
- Поясніть різницю між датою заходу сонця і періодом відстрочки.
- Опишете, як ви відповідаєте на запит зовнішнього партнера на додаткове час до дати заходу сонця.
Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Недоліки: Не
Ефективне повідомлення про запланований API-депресія вимагає більше, ніж просто заяву фактів; це про управління очікуваннями і сприяння співпраці. Часто, найбільшим викликом є не що - кожен розуміє, що API з часом змінюються - але як. Розробники часто опираються змінам, які вони сприймають як розрушаючі, особливо якщо вони сильно покладаються на стару версію. Визнаючи цей опір, ми можемо створити послання підтримки. Також важливо визнати, що розробники будуть мати різні рівні розуміння та технічної експертизи; відповідно до цього, адаптація вашої мови може значно поліпшити прийом.
Розглянемо сценарій: Ви оголосили про заборону /v1/users і отримали відмову від розробника, який постійно використовував його в своїй панелі звітів. Просте «/v1/users є застарілим» ймовірно зустрінеться з розчаруванням. Замість цього, спробуйте спочатку обговорити з ними їхні потреби. Ви можете відповісти на початкове повідомлення Slack — «Гей, ми плануємо скоро забути /v1/users. Чи є якісь зауваження?» — з такими словами: «Дякую за повідомлення! Я вдячний, що ви повідомили нам, що створили важливу панель відстеження на цьому кінцевому пункті. Давайте поговоримо про те, як ми можемо забезпечити плавний перенесення ваших даних. Можеш розповісти мені про ключові показники, які ти витягуєш з /v1/users? Ми хочемо дослідити альтернативні кінцеві точки і надати підтримку для безперервного переходу. “Це демонструє емпатію, підтверджує їхні зауваження і негайно переносить фокус на спільне рішення.
Інша поширена проблема виникає під час перегляду коду. Замість простого зауваження «Заборона /oldapi», більш корисним коментарем може бути: «Ця зміна забороняє /oldapi. Поки він вилучається, ми надаємо шлях міграції до /newapi, який пропонує покращену продуктивність і функції. Будь ласка, переконайтеся, що всі виклики до /oldapi оновлені до запланованої дати [date]. Давайте обговоримо будь-які потенційні проблеми з цим переходом під час перегляду. “Це поєднує ясність про відмову з проактивним керівництвом по альтернативі.
І нарешті, пам’ятайте, що документація - ваш союзник. Добре розроблений посібник з міграції - детально описує, як саме переключитися, які зміни були внесені, і будь-які відомі обмеження - може полегшити величезну кількість тривоги розробників. Формулювати це не як нав’язування, а як * підтримка *: “Ми створили докладний посібник з міграції, який описує кроки, необхідні для переходу вашого коду з /v1/users до /v2/users. Ви можете знайти його тут: [link]. Ми також раді запланувати дзвінок, щоб провести вас через будь-які конкретні проблеми»