Як створити дружній до розробників API: найкращі практичні поради від Favbet Tech

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

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

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

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

Є певні нюанси, від яких залежить, чи буде 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:

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

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

Створення 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. Вона має бути структурованою, зручною для розробника і містити всю необхідну інформацію для інтеграції. 

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

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 тощо.

Аутентифікація: як покращити досвід розробників з 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, розробіть одразу стратегію версіонування.