Створення дружнього до розробників API означає пришвидшення інтеграції, економію ресурсів і підтримку високої репутації компанії. У Favbet Tech навчилися тонко балансувати між технічною досконалістю та зручністю. У компанії знають: навіть такі дрібниці, як детально продумані повідомлення про помилки чи суворо стандартизовані назви, можуть значно полегшити життя розробникам.

У партнерському проєкті CTO Favbet Tech Андрій Черниш розповідає про підхід компанії до проєктування якісних API, ділиться кейсами з практики компанії та порадами, як уникнути типових помилок і зробити API зручним для всіх, в тому числі й розробників.

Що таке дружній до розробників API

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

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

author avatar

Андрій Черниш

CTO Favbet Tech

Є певні нюанси, від яких залежить, чи буде API дружнім. 

  1. Структура. Вона має бути чіткою та логічною. Якщо ми говоримо про стандартизовані API, наприклад, REST чи RPC, структура — це фундамент. Без неї API просто не зможе нормально працювати. І не важливо, внутрішній це API чи зовнішній — у будь-якому випадку важливо дотримуватись послідовності та узгодженості. Приклад: якщо ми в одному місці використовуємо назву поля userId, то так само вона має називатись і в інших місцях. Без варіацій на кшталт User_ID чи userid.
  2. Помилки. Їх потрібно стандартизувати та робити зрозумілими. Наприклад, якщо при авторизації у користувача немає прав доступу — API має чітко повідомити про це. Це допомагає розробникам швидше знаходити та виправляти помилки. 
  3. Правильне використання методів. Наприклад, у REST API важливо дотримуватись призначення HTTP-методів (GET, POST, PUT, PATCH, DELETE) відповідно до ситуації. Команди мають узгодити це між собою і дотримуватись спільного підходу. Документація повинна бути актуальною й інформативною, зрозумілою та корисною для тих, хто працює з API. Саме структура, узгодженість, стандарти, чіткі помилки, правильне використання методів та хороша документація роблять API по-справжньому дружнім до розробника.

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

  • Чітка структура: послідовні назви, формати відповідей і повідомлення про помилки.
  • Стандартизація: використання стандартних методів (GET, POST тощо) і кодів статусів (200, 404, 500).
  • Документація: актуальна, доступна (наприклад, через Swagger чи Redoc) і з прикладами.
  • Зворотна сумісність: нові версії не ламають старі.
  • Стабільність: передбачувані відповіді, чіткі ліміти запитів і SLA.

А що з інтеграцією сторонніх API? Які є проблеми

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

«У нашій компанії є внутрішні стандарти щодо якості API. Щоб пояснити, наведу приклад із досвіду іншої компанії — Uber. Ще близько десяти років тому у них існувало правило: кожен сервіс повинен відповідати суворим вимогам щодо швидкодії та якості. Це стосувалося навіть внутрішніх API. Такий підхід допомагав забезпечити стабільність і надійність у роботі. Uber також вимагав, щоб їхні партнери дотримувалися аналогічного рівня — наприклад, швидко відповідали на запити. Ми не настільки жорсткі у своїх вимогах, але все ж дотримуємося високих стандартів як всередині компанії, так і з зовнішніми API»

author avatar

Андрій Черниш

CTO Favbet Tech

Ось найтиповіші проблеми при роботі з чужими API:

  • Застаріла або неповна документація.
  • Нестабільність API: зникнення полів, зміна їх типів, непередбачувані відповіді: наприклад, масив замість об’єкта.
  • Незрозумілі або неповні повідомлення про помилки – наприклад, 500 Internal Server Error.
  • Нечіткі ліміти запитів (rate limiting) або їх відсутність.
  • Відсутність чітких SLA.

З чого починається створення хорошого API

Створення API – це не лише про код, а й продуманий дизайн. 

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

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

Ці нефункціональні вимоги лягають в основу SLA (Service Level Agreements) — угод про рівень обслуговування, які визначають, що і як повинно працювати.

Коли всі ці вимоги зібрані й узгоджені, ми переходимо до проєктування самого API: що саме він робить, як виглядатимуть його запити й відповіді, які будуть ендпоінти тощо».

Ось ключові етапи:

  1. Збір вимог: з’ясовуємо, хто і як використовуватиме API. Аналізуємо бізнес-сценарії, визначаємо аудиторію та нефункціональні вимоги: затримки, ліміти, SLA.
  2. Проєктування контракту: обираємо тип API (REST, GraphQL, gRPC), описуємо ресурси, методи, помилки, пагінацію, фільтрацію.
  3. Ревю дизайну: перевіряємо логіку, послідовність і зручність перед кодингом.
  4. API-first підхід: створюємо контракт до реалізації.
  5. Автоматизація документації: використовуємо Swagger UI, Redoc, Postman Docs, Stoplight.
  6. Реалізація та тестування: юніт-тести, інтеграційні тести, контрактне тестування.

Чому компаніям варто інвестувати в дружній API?

Розробка добре структурованого, зручного у використанні та якісно задокументованого API має кілька важливих переваг.

Андрій Черниш: «По-перше, інтеграція з таким API проходить набагато швидше. Кількість повторних уточнень, непорозумінь та переписок (так званих «ітерацій back-and-forth») значно зменшується. Це означає менше витрат — як з боку команди, яка розробила API, так і з боку партнерів, які з ним працюють. 

По-друге, це скорочує time-to-market — час, необхідний для запуску нового продукту або функції. Якщо компанія витрачає менше часу на технічну інтеграцію, вона швидше рухається вперед у бізнесі. Але є ще один важливий аспект — бізнес-репутація. Якщо ваш API зручний, швидкий в інтеграції, з ним легко працювати — про це дізнаються інші».

Якщо говорити про публічний API для зовнішніх інтеграцій з продуктом, то дружній до розробників API пришвидшує інтеграцію партнерів, зменшує витрати на підтримку, полегшує масштабування та версіонування та скорочує time-to-market.

Що стосується внутрішніх API, то від створення зручного API вони отримують таки переваги:

  • різні команди можуть працювати паралельно, домовившись про API та не чекати на реальну імплементацію;
  • під час розробки виникатиме менше уточнень та потенційно менше дефектів;
  • чіткі контракти між сервісами дозволяють зменшити back and forth кількість комунікацій між командами;
  • чіткий контракт зменшує ризик випадкової поломки;
  • чіткий, прозорий, зрозумілий, ефективний API для внутрішньої комунікації підіймає культуру розробки в компанії.

Як зробити якісну API-документацію

Хороша документація – це основа хорошого API. Вона має бути структурованою, зручною для розробника і містити всю необхідну інформацію для інтеграції. 

Андрій Черниш: «Структуровану документацію досить легко реалізувати при використанні стандартів, наприклад, OpenAPI, де ми можемо описати контракт. На його основі можна автоматично згенерувати документацію — наприклад, через Swagger UI. Це сторінка, на якій видно, які є методи, запити, відповіді, можливі коди помилок та інформація про них. Цю документацію можна і варто розширити. До базової структури варто додати додаткову інформацію. Ми можемо згенерувати мінімальний опис на основі контракту, але краще додати більше деталей, щоб було менше питань до API».

Поради від Андрія Черниша:

  1. Пишіть для тих, хто нічого не знає. Якщо розробник може інтегруватися без дзвінків, документація працює.
  2. Актуальність важливіша за ідеал. Краще трохи недосконала, але свіжа документація, ніж застаріла, хоч і красива.
  3. Тестуйте документацію: попросіть нового розробника пройти інтеграцію за нею.
  4. Збирайте фідбек: користувачі бачать прогалини краще за авторів.

Андрій Черниш: «Якщо документацію пишуть розробники вручну, вона майже завжди втрачає актуальність — хтось щось забув, десь не оновив, і виникає проблема. Тому важливо інвестувати в автоматичну генерацію документації. При наявності контракту це умовно легко реалізувати. Наприклад, якщо ми працюємо з REST API, то завжди намагаємося використовувати OpenAPI як стандарт опису. 

Ми застосовуємо підхід API-first: спочатку описуємо API у YAML-файлі, а потім генеруємо документацію на його основі. До неї можна додавати додаткову інформацію про помилки, деталі запитів тощо. Але ключове — типи вхідних і вихідних даних генеруються автоматично. На мою думку, усе, що можна автоматизувати — треба автоматизувати», – вважає він.

Як підтримувати актуальність документації:

  1. Автоматична генерація OpenAPI-документації з коду.
  2. Тестування відповідності документації (contract testing) дозволяє перевірити, чи відповідає реалізація OpenAPI-специфікації (зробили це частиною нашого CI/CD).
  3. Коректна робота з API – це стандарт для команд.

У Favbet Tech зазвичай використовують Confluence, але також мають власний портал для розробників на основі Backstage.io — це open-source інструмент, створений компанією Spotify. На базі цієї платформи можна побудувати єдиний портал для розробників, де вони матимуть доступ до усього необхідного: документації, шаблонів для створення сервісів, процесів релізу, CI/CD тощо.

Андрій Черниш: «Backstage.io — це платформа з великою кількістю плагінів, яка дозволяє зібрати все в одному місці. У нашому випадку API зберігаються в одному порталі, і розробник може: переглянути всю документацію; створити новий сервіс одним кліком — каркас, залежності, шаблони створюються автоматично; запускати процес релізу та моніторингу з одного місця. І я вважаю, що кожна зріла компанія повинна мати таку інфраструктуру».

Аутентифікація: як покращити досвід розробників з OAuth 2.0

OAuth 2.0 – стандарт авторизації, який дозволяє застосункам отримувати доступ до даних без передачі паролів. Той, хто впроваджує OAuth 2.0, надає токен, який можна використовувати для авторизації. Він має обмежений термін дії, його можна валідувати, анулювати або оновити, що дуже зручно.

Якщо потрібно інтегруватися з системою, яка використовує OAuth 2.0, нема потреби створювати користувачів і зберігати паролі у власній системі. Це значно спрощує інтеграцію. З іншого боку, це ще й вигідно з погляду безпеки: OAuth покращує Developer Experience, особливо коли йдеться про роботу з чутливими даними.

Для користувача це теж зручно: достатньо натиснути кнопку «Увійти через Google/Facebook» — і він уже авторизований. 

Андрій Черниш: «Якщо ми можемо спростити роботу з логінами, паролями, авторизацією та аутентифікацією через централізовані стандартизовані протоколи, — ми маємо це робити. Не дарма існує поняття людського фактора. Будь-який сервіс або система може бути скомпрометована саме через людську помилку. І виникає проблема. Тому все, що можна – автоматизувати, стандартизувати або обмежити».

Покращення Developer Experience з OAuth 2.0:

  • Спрощення інтеграції з іншими сервісами. Розробники використовують єдиний узгоджений метод для доступу до різних API замість вивчення унікальних механізмів авторизації для кожного сервісу.
  • Для більшості мов програмування існують перевірені бібліотеки, що зменшує кількість коду, який потрібно писати власноруч.
  • Підвищення безпеки: розробникам не потрібно зберігати чутливі дані користувачів. Це зменшує ризики, пов’язані із витоком даних. Можна зосередитись на розробці основного функціоналу замість створення власної системи авторизації.
  • Спрощений UX: користувачі отримують звичний і зрозумілий процес авторизації. Єдиний механізм працює на різних пристроях і платформах.

Тестування API та зворотний зв’язок

Щоб API був зручним, у Favbet Tech його тестують комплексно: тут відбувається тестування документації, інтеграційне тестування, юзабіліті-тестування та тестування версійності.

Компанія приділяє велику увагу зворотному звʼязку та слідкує за аналітикою використання. Але також Favbet Tech пропонує Developer Sandbox – середовище для експериментів розробників без обмежень. Зворотний зв’язок збирають так:

  • Внутрішні API: через API-review сесії. Розробник готує дизайн (ендпоїнти, методи, параметри, приклади, структуру помилок, стандарти статус-кодів, механізм авторизації тощо), а команда (бекенд, фронтенд, архітектор, продакт, tech lead product owner або бізнес-аналітик) перевіряє зручність, консистентність і безпеку.
  • Зовнішні API: через пряму комунікацію з партнерами, customer support, аналітику роботи API та інструменти моніторингу (наприклад, логування помилок або метрик використання).

Версіонування та депрекейшн

Грамотне версіонування дозволяє впроваджувати зміни в API, не порушуючи роботу тих, хто вже з ним інтегрувався. 

Андрій Черниш: «Коли ми говоримо про нову версію API, зазвичай маємо на увазі мажорні (суттєві) зміни, які змінюють як сам API, так і процеси, що базуються на ньому. Ми розвиваємо продукт, адаптуємо його під нові потреби, регуляції, запити партнерів. Але просто взяти і змінити API не можна, якщо з ним уже працюють інші системи. Тому ми створюємо нову версію API, яка працює паралельно з попередньою. 

Наприклад, ми використовуємо підхід версіонування через URL: /api/v1/…, /api/v2/… тощо. У документації це теж відображено — можна обрати версію і переглянути її опис окремо. Зазвичай ми попереджаємо партнерів заздалегідь — приблизно за пів року. Ми готуємо дизайн, реалізуємо нову версію, тестуємо її, відкриваємо тестове середовище. Після релізу ми підтримуємо обидві версії одночасно впродовж 1–2 років. Це дає партнерам час для планування, внесення змін у свої roadmap і спокійний перехід на нову версію. Ми також намагаємося зберігати зворотну сумісність навіть у новій версії».

У документації мають бути чітко описані:

  • план переходу,
  • зміни в запитах і відповідях,
  • що саме потрібно змінити на боці клієнта.

Це важливо, бо API — це, по суті, спосіб комунікації між розробниками. Крім того, такі зміни мають бути узгоджені з партнерами згідно з SLA (Service Level Agreement). 

У SLA неодмінно мусить бути прописано:

  • канали комунікації,
  • строки повідомлення про зміни,
  • обов’язки провайдера API.

У Favbet Tech старі версії, зазвичай, підтримують:

  • зовнішні API: 1–2 роки,
  • внутрішні API: 3–6 місяців.

3 поради від CTO Favbet Tech щодо створення дружнього API

  1. Фокусуйтесь на користувачах. Це принцип Know Your Client. Потрібно чітко усвідомлювати, для кого ви створюєте API і яку саме проблему він має вирішити. Визначте чітку цільову аудиторію і випадки використання API. Поговоріть з потенційними користувачами перед початком проєктування. Пріоритезуйте зручність використання над технічною елегантністю.
  2. Дотримуйтесь стандартів. Архітектурні підходи та індустріальні стандарти – наприклад, REST, GraphQL, OpenAPI – існують не просто так. Якщо ви дотримуєтесь їх – це полегшує інтеграцію з вашою системою, зменшує кількість помилок та покращує сприйняття вашого API зовнішніми командами. Слідуйте за галузевим конвенціям і наявним шаблонам. Уникайте винаходу власних нестандартних підходів без вагомих причин.
  3. API – це продукт. Він має розв’язувати реальні задачі, бути зручним і ефективним інструментом для взаємодії з вашим сервісом. Тому інвестуйте в документацію і Developer Experience, розробіть одразу стратегію версіонування.