Що таке API простими словами: ключ, токен і REST на прикладах

API (від англ. Application Programming Interface — програмний інтерфейс застосунку) — це набір правил, за якими одна програма звертається до іншої: що можна попросити, в якому форматі і що прийде у відповідь. Простими словами, API — це «вікно видачі» сервісу: ви подаєте запит за встановленою формою й отримуєте результат, не бачачи, як усе влаштовано всередині.

Коли інтернет-магазин показує відділення Нової пошти просто на сторінці замовлення, а застосунок для обліку витрат підтягує покупки з картки monobank, між програмами працює саме API.

Аналогія: офіціант і меню

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

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

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

Як влаштований запит до API

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

  1. Адреса (endpoint) — URL, на який надсилають запит.
  2. Метод — тип дії: отримати, створити, змінити чи видалити.
  3. Заголовки — службова інформація, наприклад формат даних або ключ доступу.
  4. Тіло — дані, які передають серверу (для простого читання зазвичай не потрібне).

Відповідь містить код стану і, як правило, дані у форматі JSON. Найпростіший приклад — публічний курс валют monobank. Запит GET на адресу https://api.monobank.ua/bank/currency не потребує жодного ключа, тому його можна відкрити навіть у браузері. У відповідь приходить список записів, де валюти позначені числовими кодами (840 — долар США, 980 — гривня), а час записано у форматі Unix, тобто в секундах від 1 січня 1970 року. За документацією monobank, ці дані кешуються й оновлюються не частіше ніж раз на 5 хвилин.

HTTP-методи

  • GET — отримати дані, нічого не змінюючи.
  • POST — надіслати дані, наприклад створити запис.
  • PUT — повністю замінити наявний ресурс.
  • PATCH — змінити ресурс частково.
  • DELETE — видалити ресурс.

Повний перелік методів із поясненнями є в довіднику MDN.

Коди відповіді

Код стану одразу показує, чим закінчився запит. Найчастіші з них: 200 — успіх, 201 — об’єкт створено, 400 — помилка в запиті, 401 — немає дійсного ключа, 403 — доступ заборонено, 404 — ресурс не знайдено, 429 — забагато запитів, 500 — збій на боці сервера. Зручний україномовний перелік з поясненнями є в документації API Prozorro.

JSON

JSON — текстовий формат, у якому дані записують парами «назва: значення», а списки беруть у квадратні дужки. Його легко читає і людина, і програма, тому більшість сучасних API віддають відповіді саме в ньому. Формат описаний у стандарті RFC 8259.

REST API: що це

REST (Representational State Transfer) — архітектурний стиль, який Рой Філдінг описав у своїй дисертації 2000 року. Серед його ключових принципів:

  • клієнт і сервер розділені й можуть розвиватися незалежно;
  • сервер не пам’ятає попередніх запитів: кожен запит містить усе потрібне для його обробки;
  • відповіді можна кешувати;
  • з усіма ресурсами працюють через єдиний уніфікований інтерфейс;
  • між клієнтом і сервером можуть стояти проміжні шари, наприклад проксі.

На практиці «REST API» зазвичай означає таке: кожен ресурс має власну адресу, дія задається HTTP-методом, а дані передаються в JSON. Так влаштоване API Prozorro: запит GET /api/2.5/tenders повертає перелік закупівель, а GET /api/2.5/tenders/{id} — одну конкретну закупівлю.

Не кожне веб-API побудоване за REST. У Нової пошти, наприклад, запити надходять на одну точку входу, а потрібну операцію вказують у тілі запиту.

REST чи GraphQL

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

API-ключ і токен: у чому різниця

Обидва — рядки символів, які сервер перевіряє, щоб зрозуміти, хто звертається і що йому дозволено. Різняться вони призначенням і строком дії.

API-ключ — ідентифікатор застосунку чи акаунта. Його створюють в особистому кабінеті сервісу, і він зазвичай діє довго: до видалення, заміни або завершення строку, який встановив сам сервіс. Приклад — ключ Нової пошти: його генерують у бізнес-кабінеті (розділ «Налаштування», пункт «Безпека», кнопка «Створити ключ»), і, за даними сторінки інтеграції компанії, це безплатно. У запиті ключ передають полем apiKey поруч із назвою моделі (modelName), методу (calledMethod) і його параметрами (methodProperties).

Токен — ширше поняття. Часто це тимчасовий пропуск, який видають після входу чи підтвердження прав, з обмеженим набором дозволів і строком дії. Стандарт RFC 6750 описує bearer-токени: ними може скористатися будь-хто, у кого вони опинилися. Тому такі токени передають лише захищеним з’єднанням (HTTPS), бажано в заголовку Authorization, а не в адресі сторінки, а видавати їх рекомендують короткоживучими — на годину або менше.

Термінологія в сервісів різниться. Monobank називає свій персональний ключ токеном: його отримують після авторизації на api.monobank.ua і передають у заголовку X-Token. У Prozorro запити на читання переважно не потребують автентифікації, для змін брокер використовує API-ключ, а під час створення об’єкта система видає ще й окремий токен власника, потрібний для подальших змін саме цього об’єкта (документація Prozorro).

Як зберігати ключі й токени

  • Не вписуйте їх у код і не додавайте в Git-репозиторій. Тримайте секрети в менеджері секретів або хоча б у змінних середовища, а файл .env внесіть до .gitignore.
  • Не передавайте ключ у рядку адреси: Google попереджає, що ключ у параметрі URL можуть викрасти (документація Google Cloud).
  • Не вбудовуйте ключ із доступом до приватних даних у фронтенд чи мобільний застосунок, бо звідти його може витягти будь-хто.
  • Видавайте мінімально потрібні права й регулярно перевипускайте секрети, як радить OWASP.
  • Якщо ключ потрапив у публічний репозиторій, чат чи на знімок екрана, одразу відкличте його і створіть новий.

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

Що таке API Gateway

API Gateway (API-шлюз) — єдина точка входу між клієнтами та внутрішніми сервісами. За описом Microsoft, шлюз працює як зворотний проксі: приймає запити й спрямовує їх до потрібних сервісів. Крім маршрутизації, він може:

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

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

Українські API, на яких можна потренуватися

Станом на жовтень 2026 року ці сервіси мають відкриту документацію:

  • Monobank. Курс валют доступний без ключа, інформація про клієнта й виписка — з персональним токеном. Ці два методи можна викликати не частіше ніж раз на 60 секунд, а виписку за один запит видають максимум за 31 добу й 1 годину. API недоступне клієнтам до 16 років.
  • Нова пошта. Точки входу — https://api.novaposhta.ua/v2.0/json/ та https://api.novaposhta.ua/v2.0/xml/. Через API створюють експрес-накладні під час оформлення замовлення, змінюють дані в них, замовляють переадресування й повернення. Розширена документація розміщена на порталі developers.novaposhta.ua.
  • Prozorro. Публічне API системи закупівель віддає тендери, договори, плани закупівель та інші об’єкти, наприклад за адресою https://public-api.prozorro.gov.ua/api/2.5/tenders. Перелік повертається сторінками, типово по 100 записів (максимум 1000), а посилання на наступну сторінку міститься в полі next_page. Для синхронізації документація безпечною частотою запитів називає один раз на 5 хвилин.

Для першого запиту достатньо браузера: відкрийте адресу курсу валют monobank або перелік тендерів Prozorro, і побачите сиру JSON-відповідь. Для запитів із ключами, заголовками й тілом зручніше використовувати консольну утиліту curl або графічні клієнти на кшталт Postman чи Insomnia.

Незнайомі терміни з розмов розробників зібрані у словнику ІТ-сленгу, а більше матеріалів про бекенд і вебтехнології — у рубриках «Розробка» та «Веб». Якщо ви тільки вчитеся, зазирніть у розділ «Освіта».

Часті питання

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

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

Чим API-ключ відрізняється від токена?

API-ключ зазвичай діє довго і прив’язаний до застосунку чи акаунта, його створюють в особистому кабінеті сервісу. Токен частіше видають тимчасово й з обмеженими правами після входу чи підтвердження доступу. Деякі сервіси, як-от monobank, токеном називають і персональний ключ, який користувач отримує сам.

Що таке REST API?

Це API, побудоване за принципами архітектурного стилю REST: кожен ресурс має свою адресу, дії задаються HTTP-методами GET, POST, PUT, PATCH і DELETE, а сервер не зберігає стан між запитами. Дані найчастіше передаються у форматі JSON.

Як отримати API-ключ Нової пошти?

Увійдіть у бізнес-кабінет, відкрийте розділ «Налаштування» і в пункті «Безпека» натисніть «Створити ключ». За інформацією компанії, генерація ключа безплатна.

Як отримати токен monobank API?

Потрібно авторизуватися в особистому кабінеті на сайті api.monobank.ua, де видають токен для персонального використання. Станом на жовтень 2026 року API недоступне клієнтам, молодшим за 16 років.