Писання Contract-First API Design Documents англійською

Контракт-перший API дизайн є практикою визначення контракту API - зазвичай як специфікація OpenAPI або AsyncAPI - перед написанням будь-якого коду реалізації. Контракт стає джерелом правди, на яку погоджуються як виробники, так і споживачі. Написання цього контракту чітко, і навколишній проектний документ, який його обґрунтовує, є критичним комунікаційним навиком для інженерів бекенду і платформи.

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

Контракт У контексті API, контракт є формальним, машинно-читливим визначенням того, що API обіцяє надати: його кінцеві точки, схеми запитів і відповідей, коди помилок і вимоги до автентифікації. Контракт є обов’язковим — обидві сторони інтеграції покладаються на нього.

• Приклад: “Ми завершимо контракт до четвертого, щоб обидві команди могли розпочати реалізацію паралельно.” *

Схема Схема — це структуроване визначення формату даних, у якому описано поля, їхні типи і всі обмеження, такі як обов’ язкові поля або максимальна довжина. У контрактному дизайні, схеми визначаються заздалегідь і посилаються на специфікацію. Приклад: “Схема запиту вимагає поля orderId типу string і поля quantity типу integer.”

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

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

• Приклад: « Конечна точка v1 застаріла і буде вилучена через шість місяців. Будь ласка, перейдіть до v2.”*

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

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

Поширені сценарії, де використовується ця мова

** У перегляді дизайну API: ** Перед початком розробки команди переглядають запропоновані контракти. Вам слід буде сформулювати ваші вибірки дизайну і відповісти на зворотній зв’ язок. « Ми обрала схему сторінкування, засновану на курсорах, а не на відхиленнях, оскільки вона краще масштабується з великими наборами даних. »

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

** У документації для зовнішніх розробників: ** Якщо ваш API є публічним, ваш документ проекту стає документацією для розробників. Текст має бути особливо чітким, оскільки читачі не мають контексту щодо вашої внутрішньої архітектури.

Перший проект проектно-кошторисної документації

Зазвичай, добре написаний документ проектування API містить такі розділи:

** Огляд: ** Яку проблему вирішує цей API, і хто є його споживачами? Будь коротким - два або три речення.

Рішення щодо дизайну: Поясніть, який вибір ви зробили і чому. Використовуйте формат журналу рішень, якщо розглядалося декілька альтернатив: « Ми розглядали X, але обирали Y, тому що Z. »

** Резюме кінцевої точки: ** Таблиця, яка може бути прочитана людиною, у якій наведено список кожної кінцевої точки, її метод, шлях і призначення.

** Визначення схем: ** Описи ключових структур даних, написані простою англійською мовою разом з формальною нотацією схеми.

** Обробка помилок: ** Як API повідомляє про помилки, включаючи використані коди стану HTTP і структуру тіл відповідей на помилки.

** Стратегія версій: ** Як зміни будуть керуватися з часом.

Корисні фрази для документів розробки API

• Цей API дотримується REST-конвенцій і використовує JSON для всіх тіл запитів і відповідей
• Автентифікація здійснюється через символи Bearer в заголовку Authorization
• Всі часові пояси виражені в форматі ISO 8601 в UTC
• “Кінечна точка повертає список ресурсів зі сторінками. Використовуйте поле next_cursor для отримання наступних сторінок»
• «Це поле обов’ язкове для операцій створення, але необов’ язкове для операцій оновлення.»
• «Клієнти повинні розглядати нерозпізнані поля в відповіді як необмежені і ігнорувати їх»
• “Кінечна точка v1 застаріла. Підтримка буде знята з 1 січня 2027 року»
• «Ця зміна не є порушенням — ми додаємо до відповіді додаткове поле.»
• «Ми рекомендуємо опитування не більше одного запиту на секунду, щоб уникнути обмеження швидкості»
• «API слідує за семантичним версуванням. Основна версія збільшується при зміні змінних.»

Запис описів чистих кінцевих точок

Опис кожної кінцевої точки повинен відповідати на три запитання: що вона робить, що їй потрібно, і що вона повертає? Описуйте коротко і використовуйте активний голос.

Слабкий: «Ця кінцева точка використовується для отримання інформації про користувача.» Strong: « Повертає інформацію про профілі вказаного користувача. »

Описати параметри точно. Уникайте « рядкового ідентифікатора » і замість цього пишіть « UUID користувача, який повертається кінцевою точкою автентифікації. »

Практичні рекомендації

Візьміть існуючий REST API, з яким ви працюєте, або використовуйте API GitHub як публічний приклад. Напишіть двосторінковий документ проектування для однієї з кінцевих точок, так, ніби ви пропонуєте кінцеву точку вперше. Включити всі розділи, описані вище. Запрошуйте колегу переглянути цей документ і запитайте, чи може він реалізувати кінцеву точку, засновану виключно на вашому документі. Їхні питання розкриють прогалини у вашому письмі.

Наприклад, навігаційні лінії: навігаційні лінії, що використовуються для пересування

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

Уявіть, що ви щойно надіслали PR, що описує нову кінцеву точку для отримання даних клієнта. Ви отримуєте коментар перегляду коду: « Це виглядає добре, але опис трохи неоднозначний. Що саме ми очікуємо від сервера з точки зору обробки помилок?» Менш вдалею відповіддю може бути щось на зразок « Просто обробляйте помилки ». Це надзвичайно неоднозначно! Рецензент повинен розуміти * як * ці помилки повинні бути оброблені - рівень журналювання, механізм повторних спроб, конкретні коди стану HTTP - все важливо для інтеграції і стабільності. Замість цього ви можете сказати: « Сервер поверне 400 Bad Request, якщо ідентифікатор клієнта невірний, разом з докладним повідомленням про помилку у форматі JSON, у якому буде описано помилку перевірки. Ми записуємо ці помилки у журнал 2- го рівня для негайного розгляду. Бачите різницю? Переглянута формулювання встановлює чіткі очікування і зменшує неоднозначність.

Аналогічно, розгляньте розмову Slack під час обговорення дизайну. Молодший розробник може ввести: « Отже, нам слід переконатися, що цей API дійсно швидкий ». Хоча це зрозуміло, але такий вступ не є точним. Ефективнішим підходом було б: «Давайте націлимося на середній час відповіді менше 200 мс, придавши пріоритет низькій затримці для критичних операцій». Кількісне визначення цілі і вказівка метрики забезпечує конкретні цілі для команди. Або, можливо, ви пишете PR- опис: « Ця кінцева точка API буде обробляти дані клієнта ». Це занадто загально. Замість цього, «Ця кінцева точка API дозволяє клієнтам отримувати докладну інформацію про існуючих клієнтів на основі їх унікального ідентифікатора, повертаючи об’єкт JSON, що містить такі поля, як ім’я, адреса і контактні дані»

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