Що таке API? Простий посібник для тих, хто створює застосунки

API (application programming interface) — це визначений спосіб, у який одне програмне забезпечення просить інше про дані або щоб воно щось зробило. Ваш застосунок надсилає запит у погодженому форматі — «дай бронювання на завтра», «спиши 20 євро з цієї картки», «підсумуй цей текст» — а інша система повертає структуровану відповідь. API — це те, як частини застосунку розмовляють між собою і як ваш застосунок користується зовнішніми сервісами, такими як платежі, електронна пошта, карти і ШІ.

Чому API важливі, коли ви створюєте з ШІ

Майже кожен корисний застосунок складається з частин, які спілкуються через API:

• Всередині вашого застосунку екрани в браузері викликають API вашого власного бекенду, щоб завантажувати і зберігати дані.
• Ззовні вашого застосунку ваш бекенд викликає API інших компаній: Stripe — щоб приймати платежі, поштовий провайдер — щоб надсилати чеки, провайдер моделей ШІ — щоб генерувати текст.

Коли ви просите ШІ-конструктора «прийняти оплату» або «додати ШІ-підсумок», він насправді пише код, який викликає API. Розуміння основ допомагає зрозуміти, що саме ШІ потребує від вас (зазвичай обліковий запис у цьому сервісі та ключ API), де речі можуть піти не так і скільки це коштуватиме.

Побутова аналогія

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

• Меню — це документація API: перелік того, що можна замовити і як.
• Офіціант — це API: єдиний погоджений спосіб, яким запити надходять, а відповіді виходять.
• Кухня — це інша система: вам не потрібно знати, як вона працює всередині.
• Ваше замовлення — це запит; тарілка — це відповідь.

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

Як працює запит до веб-API

Більшість API, з якими ви зустрінетеся, — це веб-API, які працюють через HTTP, той самий протокол, яким користується ваш браузер. Кожен запит має кілька частин:

А кожна відповідь має:

JSON (JavaScript Object Notation) — це простий текстовий формат імен і значень у фігурних дужках. Це стандартний спосіб обміну даними у веб-API.

REST: найпоширеніший стиль

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

PUT також існує і за конвенцією замінює весь запис, тоді як PATCH змінює лише ті поля, які ви надіслали.

Найчастіші коди статусу:

Коли ваш застосунок ламається, код статусу часто є найшвидшою підказкою. 401 від платіжного провайдера зазвичай означає відсутній або неправильний ключ API; 429 означає, що ви викликаєте API занадто часто.

REST — не єдиний стиль: існують також GraphQL і API в стилі RPC, але REST — це те, що використовує більшість сервісів і бекендів, створених ШІ.

Практичний приклад: підтвердження бронювання

Коли клієнт бронює стрижку в застосунку салону, за секунду-дві може відбутися кілька викликів API:

1. Сторінка бронювання в браузері надсилає POST /api/bookings з послугою, часом і даними клієнта на ваш бекенд.
2. Ваш бекенд перевіряє, що слот вільний, зберігає бронювання в базі даних і повертає 201 Created.
3. Ваш бекенд викликає API поштового провайдера зі своїм секретним ключем: «надішли це підтвердження на lena@example.com».
4. Якщо є завдаток, ваш бекенд просить API платіжного провайдера створити сесію оплати і надсилає клієнта туди.
5. Пізніше платіжний провайдер викликає ваш застосунок, щоб повідомити, що оплата пройшла. Цей зворотний виклик — це webhook.

Перші два кроки — це ваш власний API між frontend і backend. Кроки 3–5 — це API сторонніх сервісів.

Поширені терміни

Поширені помилки і хибні уявлення

• Секретні ключі у фронтенді. Усе, що в коді виконується в браузері, може побачити будь-хто, хто відвідає сайт. Секретні ключі мають лишатися на сервері, у змінних середовища або секретах.
• Вставляти ключі в чат. Історія чату може зберігатися. Натомість користуйтеся функцією секретів конструктора і замініть будь-який ключ, який ви розкрили.
• Вважати, що API безкоштовний. Багато API беруть плату за запит або за одиницю використання — API моделей ШІ беруть плату за токени. Перевіряйте ціни і встановлюйте ліміти витрат. Див. як використовувати API LLM.
• Не обробляти збої. Зовнішні сервіси падають, мають тайм-аути і досягають лімітів. Просіть розумні повідомлення про помилки і повторні спроби.
• Довіряти браузеру. Ваш власний API має сам перевіряти дозволи. Приховання кнопки не зупиняє того, хто викликає ендпоінт напряму.
• Використовувати бойові ключі під час тестування. Користуйтеся ключами тестового режиму, доки не будете готові до запуску.

Що попросити у вашого ШІ-конструктора

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

API в Mythex

Mythex може створити ваш власний API — як частину веб-застосунку або як окремий бекенд на Node, Python (FastAPI), C# чи Java, що працює разом з вашим frontend — і написати код, який викликає сервіси ззовні. Ключі цих сервісів ви додаєте як секрети проєкту, а не в чаті, і вони доступні вашому застосунку в попередньому перегляді і після публікації. Рецепти в документації для інтеграції будь-якого API і створення REST API-бекенду.

Запитання