API Vocabulary: 30 Terms Every Backend Developer Must Know (англійською)

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

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

Це 30 термінів, які постійно з’являються в дизайні API, перегляді коду і спілкуванні з зацікавленими сторонами.

---

Частина 1: Основні концепції API

** 1. API (англ. Application Programming Interface) — інтерфейс програмування застосунків Визначений контракт, який дозволяє одному з компонентів програмного забезпечення спілкуватися з іншим. Коли ви створюєте API, ви визначаєте які запити є чинними і які відповіді буде повернено.

«Ми виставляємо публічний API, щоб треті сторони могли інтегруватися з нашою платформою без доступу до нашої бази даних безпосередньо»

2. Конечна точка Вказана адреса URL, яку ваш API використовує для виконання певної дії. Кожна кінцева точка представляє ресурс або дію.

«Кінечна точка /users/{id}/orders повертає всі замовлення для даного користувача»

** 3. Запит** Повідомлення, надіслане клієнтом до API з проханням виконати певну дію — отримати дані, створити запис, викликати дію.

«Клієнт відсилає запит POST до /checkout з вмістом кошика в тілі.»

** 4. Відповідь** Що API надсилає назад після обробки запиту — зазвичай, це код стану і тіло з даними або повідомленням про помилку.

API відповідає з 200 OK і JSON об’єктом, що містить профіль користувача

**5. Вантажний Фактичний вміст даних тіла запиту або відповіді — не заголовки або метадані, а лише самі дані.

«Запит на завантаження включає електронну пошту користувача, ім’я і гешований пароль.»

** 6. Заголовок** Метадані, долучені до запиту або відповіді. Заголовки містять інформацію про тип вмісту, ключі розпізнавання, інструкції щодо кешування і відомості щодо обмеження швидкості.

Заголовок Authorization повинен включати чинний символ Bearer для всіх автентифікованих кінцевих точок

** 7. Методи HTTP (вербальні)** Типи дій у API REST:

Method	Common use
GET	Retrieve a resource — read-only, no side effects
POST	Create a new resource
PUT	Replace an existing resource entirely
PATCH	Update part of an existing resource
DELETE	Remove a resource

«Ми використовуємо PATCH замість PUT, тому що ми тільки оновлюємо електронну пошту користувача — не замінюємо весь запис»

---

Частина 2: HTTP-код стану

Коди стану скажуть вам, що сталося. Знаючи лексику, ви зможете негайно читати журнали і повідомлення про помилки.

** 8. 2xx — Успіх ** Запит було отримано, зрозуміло і успішно оброблено.

• 200 OK — стандартний успіх
• 201 Created — новий ресурс був створений (використовується після успішного POST )
• 204 No Content — успіх, але не повернення тіла (поширене після DELETE )

Після того, як користувач створює новий проект, API повертає 201 Created з ідентифікатором проекту в заголовку Location

** 9. 3xx — Переспрямування ** Клієнт повинен виконати додаткові дії — зазвичай, виконати переспрямування.

• 301 Moved Permanently — ресурс має новий постійний URL
• 302 Found — тимчасове перенаправлення
• 304 Not Modified — кешована версія все ще чинна (використовується з ETags)

** 10. 4xx — Помилки клієнта ** Проблема на стороні клієнта — помилковий запит, відсутня автентифікація, неправильний ресурс.

• 400 Bad Request — неправильно сформований запит, відсутні обов’язкові поля
• 401 Unauthorized — потрібна автентифікація або невірний токен
• 403 Forbidden — автентифіковано, але не дано права доступу до цього ресурсу
• 404 Not Found — ресурсу не існує
• 409 Conflict — запит конфліктує з поточним станом (наприклад, дублікат електронної пошти)
• 422 Unprocessable Entity — синтаксично коректний, але семантично неправильний (поширений при помилках перевірки)
• 429 Too Many Requests — обмеження швидкості перевищено

Якщо термін дії токена закінчився, ми повертаємо 401. Якщо користувач автентифікований, але не має дозволу, ми повертаємо 403.”

** 11. 5xx — Помилки сервера ** Щось пішло не так на сервері.

• 500 Internal Server Error — загальна, неочікувана помилка
• 502 Bad Gateway — служба попереднього рівня повернула невірну відповідь
• 503 Service Unavailable — сервер не працює або перевантажений — часто тимчасовий
• 504 Gateway Timeout — служба попереднього рівня не відповіла вчасно

«503 під час розгортання очікувалося — у нас були перевірки стану балансу завантаження, які зазнали невдачі, поки нові контейнери нагрівалися»

---

Частина 3: REST & API Design Vocabulary (англійською)

12. REST (Передача представлення стану) Стиль архітектури для створення API за допомогою HTTP. RESTful API є безстатеві, ресурсно-засновані, і використовують стандартні методи HTTP.

Наш публічний API є RESTful — кожна кінцева точка представляє ресурс, і ми використовуємо стандартні HTTP дієслова для операцій

13. Ресурс Іменник — об’ єкт, яким керує ваш API. У REST, кінцеві точки організовані навколо ресурсів.

Основні ресурси в нашому API: users, orders, products, і payments

14. JSON (JavaScript Object Notation) Стандартний формат даних для більшості сучасних REST API — легкий, зрозумілий для людини, широко підтримується.

“Всі наші кінцеві точки приймають і повертають JSON. Встановіть Content-Type: application/json у заголовках ваших запитів»

15. Параметри запиту Пара ключ- значення, додана до адреси URL після ? для фільтрування, впорядкування або сторінкування результатів.

«Використовуйте ?status=active&page=2&limit=20 для отримання другої сторінки активних користувачів»

16. Параметри шляху Змінна, вбудована у шлях URL, для ідентифікації певного ресурсу.

У /orders/{orderId}, orderId є параметром шляху — він ідентифікує, в якому порядку ви працюєте

**17. Сторінка (англ.) Розбиття великих збірок результатів на сторінки, щоб уникнути повернення всіх результатів одночасно.

API використовує курсор-засноване сторінкування — кожна відповідь включає next_cursor значення для наступної сторінки

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

«Публічний API обмежений швидкістю до 100 запитів на хвилину на API ключ. Перевищені обмеження повертають 429 Too Many Requests. ”

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

«Ми версіюємо через URL шлях — /v1/users і /v2/users співіснують. Нові клієнти повинні використовувати v2»

---

Частина 4: Автентифікація та безпека

20. Автентифікація (AuthN) Перевірка * того, хто * дзвонить — доказ ідентичності.

“Автентифікація здійснюється за допомогою токенів JWT. Включити токен в заголовок Authorization: Bearer <token>»

21. Авторизація (AuthZ) Визначення * того, що * має право робити розпізнаний викликаючий.

“Авторизація заснована на ролях. Редактори можуть оновлювати пости, але тільки Адміністратори можуть їх видаляти»

22. Ключі API Статичний секретний токен, який використовується для ідентифікації і автентифікації клієнтської програми.

Включити ваш API ключ в заголовок X-API-Key для всіх запитів

**23. «Тіньовий охоронець» (фр Токен доступу (часто JWT), який включено до заголовка Authorization для підтвердження ідентичності виклику.

«Після автентифікації, зберігайте токен Bearer безпечно — він надає доступ до всіх кінцевих точок, для яких користувач має дозвіл»

**24. Офіційний сайт 2.0 Система авторизації, яка надає змогу користувачеві надати програмі доступ до його даних без спільного використання пароля.

«Ми використовуємо OAuth 2.0 для сторонніх інтеграцій — користувачі надають програмі доступ до обсягів їх облікових записів без надання своїх реквізитів»

---

Частина 5: Розширені концепції API

**25. Імпотентність Операція є ідемпотентною, якщо її виклик декілька разів дає той же результат, що і виклик одного разу. GET, PUT, і DELETE є ідемпотентними; POST не є.

«Кінечні точки обробки платежу є idempotent — включають заголовок Idempotency-Key, щоб запобігти дублюванням платежів, якщо клієнт повторює спроби на тайм-аут»

**26. Без громадянства Кожен запит API містить усю інформацію, необхідну для його обробки — сервер не зберігає стан сеансу між запитами.

«REST APIs є безстатеві за дизайном. Кожен запит повинен включати у себе токен аутентифікації; сервер не пам’ятає попереднього виклику»

**27. Веб-сайт (англ.) Механізм, за допомогою якого ваш сервер надсилає дані до адреси URL клієнта, коли відбувається подія — це протилежне до стандартного запиту.

“Замість того, щоб перевіряти стан платежу, підпишіться на наш веб-хаок. Ми будемо POST до вашої кінцевої точки негайно після завершення оплати»

**28. «Світанок» (англ. Sunset) Коли кінцева точка або версія API є * застарілим *, вона все ще працює, але заплановано її вилучення. Когда заходит солнце, его снимают.

«Кінечна точка /v1/search є застарілим з березня 2026 року і буде захід сонця 1 вересня 2026 року. Будь ласка, перейдіть до /v2/search. ”

29. Договору про рівень обслуговування (SLA) Формальний договір, що визначає очікувану доступність і продуктивність API.

«Наше API SLA гарантує 99,9% часу роботи і максимальний час відповіді 500 мс на 95-му процентилі»

** 30. Контракт/API контракт** Формальна специфікація, яка визначає, які запити є чинними і які відповіді гарантовані — часто документ OpenAPI/Swagger.

“Перед початком будь-яких інтеграційних робіт, отримайте контракт API від команди платформи. Він визначає кожне поле, тип і код помилки.”

---

Швидка реакція

Term	One-line definition
Endpoint	A specific URL for a specific operation
Payload	The data content of a request or response body
Idempotent	Same result whether called once or many times
Rate limiting	Max requests allowed per time window
Deprecation	Still works, but scheduled for removal
Webhook	Server pushes data to you when an event happens
AuthN	Who are you? (authentication)
AuthZ	What can you do? (authorization)
Stateless	Each request is self-contained, no session state
SLA	Guaranteed uptime and performance levels

---

Використання цих термінів у комунікації

Знати терміни недостатньо — вам потрібно правильно використовувати їх у розмовах і документації.

В обзоре кода:

«Ця кінцева точка не є ідемпотентною — якщо клієнт повторить спробу на мережевому тайм-ауті, ми можемо створити дублікати записів. Додати заголовок Idempotency-Key»

На встрече по планированию:

“Ми повинні переглянути цю зміну. Якщо ми змінимо схему відповіді без зупинки версії, ми розірвемо існуючі інтеграції»

В одном случае после смерти:

«Каскад 503 був викликаний, коли API платежів перевищив наш тайм-аут і почав повертати відповіді 504 на всі автентифіковані запити»

** У документації клієнта: **

«Кінець /v1/reports застарів. Захід сонця буде 30 червня 2026 року. Будь ласка, перейдіть до /v2/reports, який підтримує всі ті ж параметри плюс поліпшене фільтрування»