Як оголосити API Rate Limit Change в англійській мові

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

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

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

** Обмеження** — сповільнення або затримка запитів, якщо клієнт наближається до обмеження, на відміну від їх прямого відхилення.

• “Замість того, щоб відразу ж відкидати запити, якщо ви досягли обмеження, ми обмежуємо їх збільшенням затримки — ви побачите повільніші відповіді, перш ніж побачите помилки.” *

** 429 Забагато запитів ** — стандартний код стану HTTP, який повертається, коли клієнт перевищує обмеження швидкості. “Якщо ви перевищите новий поріг, запити повертатимуть стан 429 Too Many Requests замість попереднього 200 OK.”

** Заголовки обмеження швидкості ** — заголовки відповідей (наприклад, X-RateLimit-Remaining і X-RateLimit-Reset ), які повідомляють клієнту, скільки запитів у нього залишилося і коли буде скинуто обмеження.

• “Ми додаємо заголовки обмеження швидкості до кожної відповіді, щоб ваша інтеграція могла проактивно відмовитися від виконання перед досягненням обмеження, а не виявляти його за допомогою помилок.” *

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

Структурування оголошення

• ** Що змінюється**: « Починаючи з [дата], обмеження швидкості для кінцевої точки /search зміниться з 1000 запитів на годину до 300 запитів на годину. »
• ** Чому **: “Ця зміна необхідна для того, щоб підтримувати платформу стабільною для всіх клієнтів - невелика кількість інтеграцій споживала непропорційну частку потужності.”
• ** Кому це стосується **: « Це впливає на всі ключі API на рівнях Free і Pro. На клієнтів рівня підприємства ця зміна не впливає»
• ** Що робити **: « Якщо ваш інтегрований обсяг перевищує 300 запитів на годину, ми рекомендуємо вам розподіляти запити або кешувати відповіді, якщо це можливо. » Див. наш посібник з міграції для конкретних шаблонів»
• ** Часова шкала **: « Граціозний період починається з [дата] і застосування починається з [дата] — у вас є чотири тижні на внесення змін до нового обмеження. »

Обробка Pushback розробника

• «Я розумію, що це значна зміна для інтеграцій великого обсягу — ми раді обговорити нетиповий ліміт для вашого випадку використання, якщо стандартний рівень не підходить до ваших потреб»
• «Це не було рішення, яке ми зробили легко — попередні обмеження викликали погіршення продуктивності для більшості клієнтів під час годин пік»
• Якщо нове обмеження блокує критичний випадок використання, будь ласка, зверніться безпосередньо, і ми будемо працювати з вами над короткостроковим винятком, поки ви налаштовуєте свою інтеграцію

Забезпечення керування міграцією

• «Найбільш поширеним виправленням, яке ми бачили, є кешування відповідей для даних, які не змінюються часто — багато інтеграцій повторно отримували ті ж дані на кожен запит»
• «Розгляньте можливість використання наших webhook подій замість опитування — це виключає необхідність частих запитів повністю для більшості випадків використання»
• Якщо ви здійснюєте кілька пошуків, наша нова кінцева точка приймає до 100 ідентифікаційних номерів за запит, рахуючи як один запит проти вашого обмеження швидкості

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

1. ** Надавайте попередження, а не сюрприз у той же день. ** Період відстрочки, навіть короткий, значно зменшує кількість злості, яку ви отримаєте від співробітників підтримки.
2. ** Поясніть « чому » коротко, але чесно. ** Розробники набагато більше прощають зміну обмеження швидкості, коли вони розуміють, що це захищає загальну стабільність платформи, а не довільне обмеження.
3. ** Надати шлях, а не лише обмеження. ** Сполучення оголошення з конкретним керівництвом щодо переходу перетворює неприємну зміну на проблему, яку можна вирішити.

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

1. Напишіть резюме з двох речень, у якому оголошується про зменшення обмеження швидкості з 1000 до 300 запитів на годину, включаючи дату вступу у дію.
2. Надіслати чернетку відповіді розробнику з проханням про виняток, оскільки нове обмеження порушує їх інтеграцію.
3. Написати одну підказку щодо перенесення для розробника, інтеграція якого запитує ту саму кінцеву точку кожні декілька секунд.

Зв’язані ресурси

• Як написати повідомлення про знищення API англійською мовою
• Як написати API Versioning Announcement англійською мовою
• Як писати повідомлення про помилки Clear API англійською мовою

Національні мови: мова ненаціональних меншин

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

Однією з ключових областей є * ясність впливу *. Просто сказати «Обмеження швидкості змінилися» недостатньо. Розглянемо формулювання: «Зважаючи на збільшений попит і постійні зусилля з оптимізації, ми скоригували обмеження швидкості API для [конкретної кінцевої точки / сервісу]. Це означає, що програми, які перевищують [нове обмеження] запитів за [часовий проміжок], можуть відчувати зниження продуктивності. » Зауважте, що у цьому тексті додано слова « через », « збільшення попиту » і « спроби оптимізації ». Ці фрази містять контекст — * причину * зміни. Аналогічно, уникайте надто технічного жаргону, наприклад, «дротування», якщо це не відразу зрозуміло. Замість цього використовуйте такі терміни, як «обмеження запитів» або «обмеження використання», а потім поясніть, що це означає в практичному сенсі. Іншим цінним методом є явне затвердження * того, що розробники повинні зробити *. Наприклад, « Будь ласка, перегляньте код вашої програми, щоб переконатися, що він відповідає новому обмеженню швидкості. Якщо ви очікуєте перевищення цих обмежень, ми рекомендуємо дослідити такі варіанти, як кешування або реалізація стратегій зворотного тиску. ”

Крім того, розгляньте, як оголошення доставляються по різних каналах зв’язку. Повідомлення Slack, яке повідомляє про зміну обмеження швидкості, має бути коротким і чітким: « Для вашого відомства — обмеження швидкості API для [кінцева точка] було оновлено до [нове обмеження]. Докладніше про оновлення можна дізнатися за адресою: [посилання].” Проте, більш формальний опис у описі запиту на звантаження потребує більшої кількості відомостей. Ось приклад: «Ця PR включає оновлення конфігурації обмеження швидкості для кінцевої точки /users. Попереднє обмеження 100 запитів за хвилину було збільшено до 500 запитів за хвилину, що відображає останнє зростання користувачів і нашу прихильність до надання надійної служби. Ми додали новий виняток RateLimitExceededError, щоб елегантно обробляти ці ситуації. Будь ласка, перегляньте оновлену документацію [посилання] і переконайтеся, що ваші програми налаштовані відповідно. » Включення « відображає останнє зростання користувачів » надає контекст — розробникам потрібно розуміти * чому * відбувається ця зміна, а не тільки * що * вона відбувається.

Нарешті, активна підтримка може зробити величезну різницю. Заохочуйте розробників ставити питання і будьте готові пояснити зміни у різноманітних способах. Це цілком прийнятно (і заохочується!) пропонувати один-на-один керівництво. Проста фраза, наприклад, «Давайте пройдемося разом» або «Чи хочете ви, щоб я надіслав вам швидку діаграму, яка ілюструє, як працюють нові обмеження?», Демонструє емпатію і підтримку, сприяє більш спільному середовищу, де розробники відчувають себе комфортно, запитуючи про пояснення, не відчуваючи залякування. Пам’ятайте, чітке спілкування - це будівництво розуміння - а не просто передача інформації.