Англійська мова для API Design Reviews

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

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

** Контракт (контракт API) ** Формальна угода між API і його користувачами про форми запитів і відповідей, коди стану і поведінку - це те, що перегляд дизайну насправді оцінює.

• Приклад: « Зміна типу цього поля порушує контракт для кожного існуючого користувача, тому нам потрібна стратегія версії, а не зміна на місці. » *

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

** Зворотна сумісність ** Властивість нової версії API, яка продовжує працювати правильно для користувачів, збудованих за попередньою версією, без необхідності змінювати щось. Приклад: «Додання цього додаткового поля є зворотньо сумісним, але вилучення іншого поля не є — існуючі клієнти, які залежать від нього, будуть вимкнені без повідомлення.»

Все изменилось Будь-яка модифікація контракту API, яка може призвести до того, що існуючі, правильно написані споживачі не спрацюють або будуть поводитися неправильно.

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

Страницирование Стратегія повернення великих результатів у менші, послідовні шматки, а не всі за раз, зазвичай використовуючи або зсув-засновані або курсор-засновані підходи.

• Приклад: « Нам слід використовувати сторінкування за курсором замість сторінкування за зміщенням, оскільки сторінкування за зміщенням дає неоднозначні результати, якщо елементи вставляються або вилучаються між запитами сторінок. » *

** Ресурс (RESTful ресурс) ** Сутність з назвою, відкрита API, зазвичай представлена як іменник у шляху URL, зі стандартними методами HTTP, що представляють дії з нею. Приклад: “Ця кінцева точка моделюється як дія, а не як ресурс — давайте переглянемо, чи слід її виразити як POST до колекції ресурсів замість цього.”

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

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

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

В обзорах дизайна:

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

** У коментарях до запитів на звантаження або пропозицій: **

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

** У дискусіях з користувачами API: **

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

Фрази, яких слід уникати

**Сказати “це не відчувається правильно” без назви конкретного питання. ** Замість цього скажіть: «Ця кінцева точка не є ідемпотентною, що є ризикованим, враховуючи поведінку повторних спроб на неоднорідних мережах» — неясний дискомфорт не дає автору нічого, що можна змінити.

**Сказати «просто додайте номер версії» без стратегії. ** Замість цього скажіть: «Яка наша стратегія версії тут — заснована на URL, заснована на заголовку, або еволюція тільки з додаванням?» — перехід прямо до версії без явної стратегії має тенденцію виробляти непослідовне версування по всій поверхні API з часом.

Скажите “это небольшая поправка” для чего-то, что изменяет контракт. Замість цього скажіть: « це змінює форму відповіді, що є зміною, яка розбиває, незалежно від того, наскільки малим виглядає diff » — зміни у договорі повинні оцінюватись за їх впливом на споживачів, а не за розміром коду diff.

Краткий справочник

Term	How to use it
contract	”Changing this field’s type breaks the contract for existing consumers.”
idempotency	”This endpoint isn’t idempotent, which is risky under client retries.”
backward compatibility	”Adding an optional field preserves backward compatibility.”
breaking change	”Renaming this field is a breaking change even if the data is the same.”
pagination	”Cursor-based pagination avoids duplicate or skipped items.”
versioning strategy	”Our strategy favors additive-only changes over frequent major bumps.”

Ключеві моменти

• Назвіть конкретну проблему контракту (неможливість виконання, зміна, послідовність сторінкування), а не висловлюйте неясний дискомфорт з приводу запропонованого дизайну.
• Оцінюйте зміни за їх впливом на існуючих користувачів, а не за тим, наскільки малим виглядає відмінність коду — зміна назви одного рядка все одно може бути зміною, яка призведе до розриву.
• Згодитися на стратегію версії явно перед тим, як буде здійснено зміну, замість типового вибору ad hoc версії.
• Рекомендуємо використовувати сторінкування за допомогою курсора замість сторінкування за допомогою зміщення, якщо набори результатів можуть змінюватися між запитами сторінок, і пояснюємо, чому це так, з точки зору послідовності.
• Зберігати відповіді на помилки у вигляді послідовних форм на всій поверхні API, і викликати невідповідності під час перегляду так само, як і будь- які інші невідповідності у контрактах.

Наприклад, слово «навигація» (navigation) означає «пересування» (navigation) з англійського мови

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

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

Крім того, вивчення того, як дипломатично обґрунтовувати потенційні проблеми, має вирішальне значення. Замість того, щоб негайно реагувати оборонно на коментар на кшталт: «Ця кінцева точка здається надто складною», спробуйте відповісти на зразок: «Дякую за підняття цієї теми; Я ціную можливість прояснити мої міркування. Я був уважним до складності під час проектування і вірю, що ця структура дозволяє майбутню розширюваність, зберігаючи ясність. “Або, в розмові Slack, замість того, щоб сказати “Це неправильно”, розгляньте “Чи можемо ми дослідити альтернативні підходи? Можливо, [запропонуйте конкретну альтернативу] досягне такого ж результату зі зменшеним когнітивним навантаженням?»

Нарешті, пам’ятайте про важливість визнання невизначеності. Це цілком прийнятно - і демонструє інтелектуальну чесність - сказати: “Я все ще оцінюю найкращий підхід для цього конкретного сценарію і вітаю будь-які ваші погляди.” Уникайте абсолютних тверджень на кшталт “Це * є * правильним шляхом”, які можуть негайно поставити інших в оборону. Сфокусуйтесь на спільному дослідженні і спільному розумінні. Вбудовування цих конкретних фраз у ваш словник значно поліпшить ваші можливості навігації у перегляді дизайну API з впевненістю і зробить ефективний внесок у технічні обговорення.