Коли ми написали соте API ми зрозуміли...

Ми Perfect Solutions минулого тижня написали сотий по рахунку API. За все це час, ціною граблів, милиць, велосипедів і рефакторинга, ми зрозуміли, що виробили відмінну стратегію «як писати API і припинити біль і страждання».

Цей пост про версировании, підтримки, багфиксинге і повному циклі життя API.

Під катом немає фото з великим трафіком, ні срібних куль, тут навіть немає картинки для залучення уваги — тільки корисна елементи нашого досвіду. Під катом методологія, вироблена на реальному досвіді розробки, набитих шишках і зламаних грабляхъ.

Продуктовий підхід

API — не набір функцій для всіх», не «набір для вирішення будь-яких завдань», не «зробити і забути».

API — це продукт, при тому продукт, яким будуть користуватися розробники. Вам не вдасться «продати» їм погане API, видавши за гарне. На всі питання відповість час.

Що таке продуктовий підхід до API? Це означає, що API) складається з функцій і багів. Фічі повинні бути прості і атомарны: один метод API — сприймається як одна фіча. Фіча, реєстрація користувача через API? Так, фіча! Фіча, відсилання push-повідомлення? Фіча!

А це означає, що всі методи API зобов'язані бути продумані, описані, розроблені і протестовані — пройти повний цикл розробки. Найбільші біди в плані ставлення розробників до API — його недолугість.

Атомарність операцій

Якщо Ваше API робить в одному методі 3 INSERT в СУБД — там зобов'язана бути транзакція. Якщо її немає — це не просто буде причиною проблем, але і причиною незнайдених і невідтворюваних з інтерфейсу проблем.

І ще важливий момент в понятті атормарности. Фіча — атомарна. Якщо при реєстрації нового юзера з API йому зобов'язані бути вказані ролі (із системи прав) — означає метод API для реєстрації користувача зобов'язаний в одному запиті робити обидві речі:

  • Створювати користувача
  • Робити assign переданого списку ролей


Наприклад ось такий метод, в разі yii2:
public function actionRegister($username, $password, array $roleNames)
{
...
}


Перевірка всіх вхідних параметрів і відповідність протоколів

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

Стандартні http-відповіді відповідні реальності — це важливий момент для спрощення підтримки і дебага. Некоректний запит, постійна валідація — «400 Bad Request», Внутрішня помилка — «500 Internal Server Error». Це дуже важливо для логування (в логах nginx) і лагодження всіх майбутніх багів. Якщо API завжди віддає статус 200 — буде дуже складно знайти в логах причини помилок.

Ви будете чинити баги

Ви не викинете API, не зробите потім нову версію». Ви будете чинити баги в цій версії API, в цьому коді і прямо завтра.

Я це кажу до того, що як будь-який продукт, API — то що доведеться налагоджувати, тестувати і підтримувати. А значить є самий звичайний набір правил:
  • Дотримуйтеся протокол (як мінімум Status Code)
  • Логируйте все — на стороні API логируйте запити і відповіді, на стороні клієнта — те ж саме. Кумедний момент — воно ще й може відрізняться ;-)
  • Тестуйте його, робіть рев'ю коду і пам'ятайте що API — це продукт, користувачі якого — розробники
  • Робіть спеціальний параметр для дебага — щоб на стороні клієнта можна було отримати не тільки відповідь від API, але і всю налагоджувальну інформацію. Поряд з відповіддю.


Ніколи не вірте в те що Ви винайшли спосіб версирования API



Версирование API допомагає втрачати зворотну сумісність в нових методах, не викидаючи старі методи, залишаючи їх в старій версії. Інтернет пропонує безліч способів версировать API. Способів для різних фреймворків, підходів і всього іншого, але срібної кулі немає. За те є в магазин який легко влазить майже будь-яка куля — location в nginx.
location /api/v1/ {
...
}

location /api/v2/ {
...
}

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

Document Drive Development

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

Викладіть новий метод на бойовий сервер — просто скопіюєте документацію із завдання у ваше сховище документації. І вуаля — ваша документація завжди актуальна.

ФП, як аналогія

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

Методи API повинні бути атомарны, але при цьому достатні. І дуже дрібне разбиене і зворотна сторона — призведуть до проблем.

Удачі!

Я коротко виклав наш суб'єктивний досвід розробки API, але не навів жодного осмисленого коду — у вас все одно буде ваш код.

А ось все це коротко у вигляді тез:
  • Продуктовий підхід
  • Атомарність операцій
  • Перевірка всіх вхідних параметрів і відповідність протоколів
  • Логируйте
  • Ніколи не вірте в те що Ви винайшли спосіб версирования API
  • Document Drive Development
  • ФП, як аналогія


Джерело: Хабрахабр
  • avatar
  • 0

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.