API і FastAPI простими словами

API - це спосіб, у який програми звертаються одна до одної. Одна просить, інша відповідає. На прикладі маркетплейсу розберемо, з чого складається запит, як читати JSON-відповідь і що перевіряти, коли Claude Code підключає зовнішнє джерело даних. Наприкінці коротко уточнимо, де тут може трапитися FastAPI.

Що таке API простими словами

API (Application Programming Interface) - це програмний інтерфейс. Він визначає доступні операції та правила звернення до них. API мають не лише окремі застосунки, а й бібліотеки, операційна система, браузер. Через нього програма може попросити іншу програму або її частину щось зробити й отримати результат. Але тут здебільшого про мережеві API, тобто ті, до яких звертаються за адресою.

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

Власне, API - це контракт: "до мене можна звертатися ось так, і у відповідь я поверну ось такий результат".

Коли Claude Code пропонує підключити сервіс, йому треба з'ясувати, що можна запитати і що прийде у відповідь. Документація API описує це "меню".

Є ще короткий жартівливий ролик англійською - "How API work". Це ілюстрація до тієї самої думки, не більше. Усе потрібне є в тексті нижче.

Запит і відповідь на прикладі маркетплейсу

Уявіть маркетплейс, до якого постачальник передає товари зі своєї програми. Натискати кнопки сайту для тисяч позицій? Незручно. Тому маркетплейс надає програмні операції API. Наприклад, POST /products додає товар, а GET /reports повертає звіт.

Адресу доступної операції називають endpoint. Щоб зрозуміти запит, дивляться і на адресу, і на HTTP-метод. GET /products і POST /products можуть виконувати різні дії. GET зазвичай використовують для читання, POST - для передавання даних на обробку.

Дані часто передають у форматі JSON. Фігурні дужки об'єднують поля об'єкта, рядки записують у лапках, а список об'єктів - у квадратних дужках:

{
  "name": "Настільна лампа",
  "price": 15000,
  "count": 350
}

Клієнт надсилає запит, сервер обробляє його і повертає відповідь. Нижче скорочена схема обміну, а не повний HTTP-пакет:

POST /products
{ "name": "Настільна лампа", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created - статус відповіді, а JSON під ним - тіло з результатом. У справжньому API документація вказує endpoint, метод, обов'язкові параметри, заголовки, форму відповіді та можливі помилки. І починати безпечніше з одного тестового об'єкта, а не одразу з усього набору даних.

API - це контракт. Claude Code може написати запит, але відповідність коду контракту перевіряють за актуальною документацією і справжньою відповіддю сервісу.

Фронтенд, бекенд і API між ними

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

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

Бекенд - серверна частина застосунку. Вона обробляє оплати, зберігає замовлення, перевіряє доступ, шукає товари. Під час розробки сервер може працювати на вашому комп'ютері, після публікації - на хостингу. Користувач не отримує його вихідний код разом зі сторінкою. браузеру приходять лише відповіді на запити.

Як вони спілкуються? Через той самий API. Бекенд надає свої endpoint не лише зовнішнім постачальникам, а й своєму власному фронтенду:

ви відкрили сторінку - фронтенд смикає endpoint /products/list, бекенд повертає список товарів, фронтенд гарно їх малює;
ви натиснули "купити" - фронтенд надсилає дані на endpoint /orders, бекенд оформлює замовлення.

Дія в браузері
Запит frontend
Обробка на backend
Відповідь з даними

Отже, через API можуть спілкуватися і різні застосунки, і частини одного застосунку. У цій схемі браузер надсилає запит, backend працює з даними і повертає результат. База даних не мусить бути доступна браузеру напряму.

Запит із браузера

Вище ми сказали, що фронтенд "смикає endpoint" бекенду. Подивімося, який це має вигляд у коді. У браузері для цього є вбудована функція fetch. Вона надсилає HTTP-запит на потрібну адресу і повертає відповідь. Тіло відповіді зазвичай приходить у JSON, і його перетворюють на об'єкт методом .json().

Візьмімо довідник локалей - поєднань мови та регіональних налаштувань. Припустімо, backend уже вміє віддавати список за адресою /locales, а frontend має його показати. Наприклад, сервер повертає:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Як приходить відповідь

Фрагмент нижче виконується всередині асинхронної функції-обробника сторінки. Він лише отримує дані, а таблицю тут не малюємо.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Тепер locales містить дані для таблиці

Перевіряємо res.ok до читання даних. HTTP-помилка на кшталт 404 чи 500 сама по собі не змушує fetch викинути виняток. Окремо може не відбутися мережевий запит або не вдатися розбір JSON. Помилку з такого фрагмента має перехопити код сторінки і показати зрозуміле повідомлення. Це різні причини, хоча користувачу в усіх випадках не вдалося отримати дані. Докладніше - у посібнику MDN про fetch.

Тут є кілька дрібниць, які легко проґавити:

за замовчуванням fetch робить GET - запит на отримання даних. Інші операції задають методом; наприклад, наш маркетплейс приймає новий товар через POST;
адреса /locales відносна. У звичайній HTTP-сторінці вона звертається до кореня того самого origin. Origin визначається схемою, хостом і портом; сервер повинен мати такий маршрут;
fetch і .json() повертають результат не одразу, тому перед ними пишуть await - "дочекайся відповіді".

Якщо відкрити HTML як файл через file://, запис /locales не стане адресою вашого HTTP-сервера. Для цього прикладу сторінку відкривають через сервер, на якому реалізовано маршрут. Сам файл HTML такого маршруту не створює.

Frontend і API можуть бути на різних origin. Тоді, щоб браузер міг прочитати відповідь, сервер API має дозволити потрібний доступ через CORS. Це механізм міжсайтового доступу, а не назва будь-якої мережевої помилки. Розміщення сторінки й API на одному origin спрощує приклад, але не обов'язкове для всіх застосунків. Деталі є в описі CORS на MDN.

Хто відповідає браузеру

Хто відповідає на fetch("/locales")? Backend, і він не мусить бути написаний на Python з FastAPI. API - домовленість між програмами, а не конкретна мова. Той самий endpoint можна написати хоч на Node.js, хоч на Go чи Java. Наприклад, в обробнику сервера Node.js можна повернути підготовлений масив locales. Нижче лише фрагмент обробника, не готовий сервер:

// req і res отримані обробником, locales підготовлено заздалегідь
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Ззовні це все той самий HTTP-запит GET /locales, а у відповіді статус 200 і JSON. Frontend не потрібно знати, на чому написаний backend. Йому потрібні адреса, правила запиту і формат відповіді.

Коли Claude Code пише fetch("/locales"), попросіть показати і другу сторону. Нехай агент вкаже, який код відповідає на цей запит. Потім перевірте, що побачить користувач, якщо відповідь не прийде.

Які бувають API

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

локальні та мережеві - наприклад, API бібліотеки викликають з коду програми, а до мережевого API звертаються через мережу. Мережа може бути і внутрішньою, без відкритого інтернету;
публічні та внутрішні - публічні розраховані на зовнішніх розробників, внутрішні пов'язують частини системи. Публічний API теж може вимагати реєстрації, оплати і дозволів.

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

200 - усе добре;
201 - створено (наприклад, новий об'єкт після POST);
404 - не знайдено;
401 - запит не містить відповідних даних автентифікації;
429 - забагато запитів;
500 - внутрішня помилка сервера.

Глибоко в це зараз можна не занурюватися. Важливо вхопити саму ідею обміну запитами й відповідями. Поки що цього досить.

Завчати коди напам'ять не потрібно. На сайті http.cat кожен HTTP-статус показано картинкою з котиком.

Навіщо сервісу ключ доступу

Багато сервісів спершу просять отримати API-ключ - рядок, пов'язаний з вашим акаунтом або проєктом. Його передають у спосіб, указаний у документації, часто в заголовку запиту. Сервіс перевіряє доступ і може враховувати, скільки запитів ви зробили. В інших інтеграціях трапиться слово токен - призначення схоже, але спосіб отримання, строк дії і права можуть відрізнятися.

Без відповідного доступу запит не виконається; наприклад, сервер може відповісти 401. Перевищення частоти запитів часто позначають кодом 429. Точний сенс відповіді й дозволені обсяги дивляться в документації конкретного сервісу. А є й відкриті джерела, яким ключ узагалі не потрібен.

Секретний ключ дає доступ у межах виданих йому прав, іноді й за ваш рахунок. Його не вставляють у листування, публічний код чи Git. На боці сервера значення можна передавати через середовище процесу; змінна, що потрапила в JavaScript браузера, секрет уже не приховає. Де задати значення і як передати його програмі - окрема тема про ключі та змінні середовища.

Де шукати готовий API

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

Для пошуку зручно переглянути Postman Public API Network, каталог API і прикладів запитів. Знайдений приклад - лише відправна точка. Адресу, формат, доступ і обмеження все одно звіряйте з офіційною документацією власника сервісу.

Де тут FastAPI

FastAPI - один із фреймворків для створення API і вебсерверів на Python. Він може зв'язати endpoint з вашим серверним кодом, прийняти запит і повернути JSON-відповідь. FastAPI потрібен, коли ви створюєте власний Python backend; щоб користуватися готовим API, вивчати його не обов'язково. На рівні 7 досить упізнавати назву та розуміти цю межу. І все.

Як це працює у зв'язці з Claude Code

З цими поняттями простіше оцінювати роботу агента. Він може прочитати документацію чужого API, написати клієнтський запит або створити ваш API на FastAPI. Вам важливо бачити конкретний шлях від запиту до даних на сторінці. Хто надсилає запит, хто відповідає і як обробляється відповідь?

Наприклад, для радара землетрусів є публічний GeoJSON feed USGS. Адреса списку за останню годину:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Нижче невеликий навчальний приклад структури відповіді, з вигаданою подією і скороченим набором полів. Це не поточні дані USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Навчальна точка" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

У features лежить масив подій. Шлях features[0].properties.mag веде до магнітуди першої з них. Індекс 0 - це перший елемент масиву (так, рахують з нуля). Координати йдуть у порядку "довгота, широта, глибина в кілометрах". Агент може використати магнітуду для розміру точки, а координати - для її положення. Якщо масив порожній, першого елемента немає; якщо магнітуда дорівнює null, це невідома величина, а не нульова сила події.

Лишилося вирішити, що показувати після запиту. І це не така дрібниця, як здається:

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

Поки запит виконується, сторінка може показувати завантаження. Для перевірки різних сценаріїв зручно використовувати навчальні відповіді. Так не доведеться чекати справжнього збою сервісу чи нового землетрусу.

Доручення для Claude Code тепер може звучати так:

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

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