Як обговорювати стратегію версії API англійською мовою

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

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

** Розрив зміни ** — зміна контракту API, яка призведе до того, що існуючий код клієнта зазнає невдачі або поводиться неправильно, відрізняється від додаткової зміни, яка є зворотньо сумісною.

• “Переназва цього поля є зміною, яка призведе до руйнувань — будь- який клієнт, який буде обробляти стару назву поля, зазнає невдачі, отже, йому потрібна нова версія API, а не латка для поточної версії.” *

** Схема версії ** — механізм, який використовується для вказівки версії API, на яку спрямований запит, зазвичай за допомогою шляху URL ( /v2/ ), нетипового заголовка або переговорів щодо вмісту ( Accept заголовок тип носія). “Ми використовуємо версії, засновані на URL, а не на заголовках, в основному тому, що це легше виявити для зовнішніх розробників, які переглядають документацію.”

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

• “Діапазон застарівання для v1 становить шість місяців з сьогоднішнього дня — після цієї дати, запити v1 почнуть повертати 410 Gone.” *

** Дата закінчення дії ** — конкретна дата, коли стара версія API припинить працювати повністю, цю дату слід повідомити чітко і заздалегідь, відрізняючи її від дати оголошення про припинення дії. “Ми оголосили про зниження в січні з датою закінчення в липні — цей шестимісячний проміжок дає командам-партнерам реальний час для переходу.”

** Зворотна сумісність ** — властивість, за якої нова версія API продовжує підтримувати поведінку існуючих клієнтів, принаймні, протягом певного періоду часу, зменшуючи необхідність примусової міграції. “Ми зберегли зворотну сумісність для форми відповіді у v2, додавши нові поля замість вилучення старих — існуючим клієнтам не потрібно нічого змінювати відразу.”

** Переговори щодо версії** — процес, за допомогою якого клієнт і сервер домовляються щодо версії API, яку слід використовувати для заданого запиту, за допомогою явного версування або елегантної поведінки резервування. “Якщо клієнт не вказує заголовок версії, наша переговорна версія типово буде найновішою стабільною версією, а не відмовляє в задоволенні запиту.”

Звичайні фрази

• Чи є ця зміна зворотно сумісною, або вона вимагає нової версії API?
• «Що таке вікно знищення для старої версії — чи достатньо довго для партнерських команд реалістично мігрувати?»
• Чи ми оголосили дату закінчення, чи є «застаріла» в даний час відкритою без фактичного кінця?
• Яка версія схеми ми використовуємо тут — URL шлях або заголовок-засноване переговорів?
• Що відбувається, якщо клієнт не вказує версію — чи є розуміння поведінки за замовчуванням?

Приклади висловлювань

Пояснення рішення щодо версій у документації проекту: “Ми вводимо це як нове поле в існуючій відповіді v2, а не викликаємо в v3, оскільки це додавання і не порушує будь-яку існуючу логіку аналізу клієнта - повна зворотна сумісність, не потрібна вимушена міграція.”

Передача повідомлення про знищення зовнішнім розробникам:

• “API v1 тепер застарілий і буде знято з обліку 1 грудня. Ми рекомендуємо перейти на v2 під час цього вікна — головною зміною є реструктурований формат відповіді на помилки, задокументований в посібнику з міграції.”*

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

Професійні поради

• Класифікуйте кожну запропоновану зміну API явно як ** розрив зміни ** або не перед відправкою - випадкова розрив зміни прослизнула в «незначний» випуск є однією з найпоширеніших причин інциденту інтеграції партнера.
• Вкажіть вікно втрати чинності і дату заходу сонця як конкретні дати, а не як нечіткі терміни, на зразок « скоро » або « з часом » — зовнішні команди потребують конкретних термінів для планування роботи з перенесення.
• Обґрунтуйте вибір ** схеми версії ** явно, коли документуєте рішення щодо дизайну API — це впливає на інструменти, кешування і досвід розробника у спосіб, який варто записати.
• Описувати зворотну сумісність гарантій точно в повідомленнях про випуск — «переважно сумісний» не є тим самим зобов’язанням, що і «повністю сумісний», і їх об’єднання розмиває довіру з API- споживачами.

Практичні вправи

1. Напишіть речення, у якому буде класифіковано гіпотетичні зміни API як порушуючі або не порушуючі.
2. Написати повідомлення про застарівання з конкретною датою заходу сонця.
3. Поясніть у одному реченні різницю між версіями, заснованими на адресах URL і версіями, заснованими на заголовках.

Національна мова: мова, що використовується для спілкування між народами, що не є рідними для однієї нації

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

Однією з ключових областей є розуміння різниці між * незначним * оновленням версії (наприклад, від 1.0.1 до 1.1.0) і * головним * оновленням версії (наприклад, від 1.0 до 2.0). Просто сказати «ми оновлюємо API» не достатньо. Точнішим підходом є: «Ми вводимо основне оновлення версії, що означає, що будуть зміни, які вимагають від клієнтів мігрувати свій код». Використання таких термінів, як «переломна зміна», «міграція» і «вплив на стороні клієнта» дозволяє зацікавленим сторонам — менеджерам продукту, дизайнерам або іншим розробникам — негайно зрозуміти обсяг зміни. Інша корисна фраза: «Ця версія вводить назад несумісні зміни; ми документували їх докладно в [посилання на документацію]»

Розглянемо повідомлення Slack під час перегляду коду: «Привіт команда, я помітив, що цей PR використовує застарілу функцію calculate_total(). Ми зараз працюємо у вікні знищення для цього методу. Будь ласка, розгляньте можливість використання нової функції compute_sum() замість неї - вона оптимізована і буде повністю видалена після 3-го кварталу.” Фраза “вікно відхилення” є ключовою; вона встановлює часові рамки і нагадує про майбутнє видалення, підштовхуючи до дії без звучання обвинувачення. Аналогічно, під час написання опису завдання на завантаження, уникайте нечітких вказівок, наприклад, « API change ». Замість цього, вкажіть: « Це PR реалізує нову версію 2. 0 API, вводячи зміни, які вимагають оновлення з боку клієнта для обробки [особливої проблеми] ».

Нарешті, пам’ятайте, що активне спілкування є життєво важливим. Краще передбачати питання і звертатися до потенційних проблем заздалегідь, ніж реагувати оборонно, коли вони виникають. Фрази на кшталт «Давайте обговоримо наслідки цієї зміни для наших користувачів» або «Щоб забезпечити плавний перехід, ми надамо рекомендації щодо міграції» демонструють передбачуваність і будують довіру. Сфокусування уваги на ясній, практичній мові значно покращить вашу здатність успішно керувати цими розмовами.