04.09.2025

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

Хороше API повинне мати чітко описану документацію як саме взаємодіяти з програмою до якої це API створене.

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

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

Існує кілька основних типів архітектур API: RPC, REST, SOAP, GraphQL, websockets. Їх можна назвати «форматами», кожен з яких має унікальні характеристики та використовується для різних цілей. Є й інші формати API, але на момент написання лекції ці — найпопулярніші.

Для того щоб апки могли спілкуватися між собою, їх API потрібно будувати по єдиному стандарту. Одним із таких є REST — стандарт архітектури зв’язків аплікух і сайтів, з використання протоколу HTTP. Особливість REST в тому, що сервер не запам’ятовує стан юзера.Іншими словами, ідентифікація юзера (авторизаційний токен) і всі параметри які необхідні для виконання операцій передаються в кожному запиті. Такий підхід настільки простий і зручний, що майже витіснив всі інші.

REST

REST — це абревіатура від REpresentational State Transfer і архітектурний стиль для розподілених hypermedia (гіпермедіа – веб ресурси) систем. Рой Філдінг вперше представив його у 2000 році у своїй знаменитій дисертації. З тих пір він став одним із найбільш широко використовуваних підходів для створення веб-інтерфейсів API (інтерфейсів прикладного програмування).

REST — це не протокол чи стандарт, це архітектурний стиль. На етапі розробки розробники API можуть реалізувати REST різними способами.

Як і інші архітектурні стилі, REST також має свої керівні принципи та обмеження. Ці принципи мають бути дотримані, якщо інтерфейс служби має називатися RESTful.

Веб-API (або веб-сервіс), що відповідає архітектурному стилю REST, називається REST API (або RESTful API).

Шість принципів REST

REST базується на деяких обмеженнях і принципах, які сприяють простоті, масштабованості та відсутності стану в дизайні. Якщо сервіси відповідають цим принципам – вони і будуть називатися RESTful.

1. Uniform Interface (Уніфікований інтерфейс)

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

Наступні чотири обмеження можуть досягти єдиного інтерфейсу REST:

Ідентифікація ресурсів – інтерфейс має унікально ідентифікувати кожен ресурс, який бере участь у взаємодії між клієнтом і сервером. Маніпулювання ресурсами через представлення – ресурси повинні мати однакові представлення у відповіді сервера. Костувачі API повинні використовувати ці представлення для зміни стану ресурсу на сервері. Повідомлення з описом – кожне представлення ресурсу має містити достатньо інформації, щоб описати, як обробити повідомлення. Він також повинен надавати інформацію про додаткові дії, які клієнт може виконувати на ресурсі. hypermedia (гіпермедіа) як механізм стану – клієнт повинен мати лише початковий URI програми. Клієнтська апка повинна динамічно керувати всіма іншими ресурсами та взаємодіями за допомогою гіперпосилань. Простіше кажучи, REST визначає послідовний і уніфікований інтерфейс для взаємодії між клієнтами та серверами. Наприклад, REST API на основі HTTP використовують стандартні методи HTTP (GET, POST, PUT, DELETE тощо) та URI (уніфіковані ідентифікатори ресурсів) для ідентифікації ресурсів.

2. Client-Server (Клієнт-Сервер)

Шаблон проектування «клієнт-сервер» забезпечує поділ завдань, що допомагає компонентам клієнта та сервера розвиватися незалежно.

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

Поки клієнт і сервер працюють і обробляють дані, ми можемо переконатися, що інтерфейс/контракт між клієнтом і сервером не порушується.

3. Stateless (Без запамятовування стану)

Стейтлесс передбачає, що кожен запит від клієнта до сервера повинен містити всю інформацію, необхідну для розуміння та виконання запиту.

Сервер не може використовувати будь-яку попередньо збережену контекстну інформацією на сервері.

З цієї причини клієнтська програма повинна повністю зберігати стан сеансу. І при відправці передавати цю інформацію.

4. Cacheable (Кешування)

Обмеження кешування вимагає, кожна відповідь (респонс) неявно або явно позначала себе як кешувальну або некешувальну.

Якщо відповідь (респонс) можна кешувати, клієнт (відправник запиту) отримує право повторно використовувати дані відповіді пізніше для еквівалентних запитів і протягом визначеного періоду.

5. Layered System (Багатошарова система)

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

Простим прикладом багаторівневої системи є шаблон MVC. Шаблон MVC дозволяє чітко розділити проблеми, що полегшує розробку, підтримку та масштабування програми.

6. Code on Demand Код на вимогу (необов’язкове правило)

REST також дозволяє розширити функціональність клієнта шляхом завантаження та виконання коду у формі аплетів або сценаріїв.

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

Гіпермедіа

Формат даних відомий як тип медіа (media type). Тип медіа ідентифікує специфікацію, яка визначає спосіб обробки представлення.

Гіпертекст (або гіпермедіа) означає відображення інформації та елементів керування таким чином, що інформація стає можливістю, за допомогою якої користувач (або машина) отримує вибір і вибирає дії.

Пам’ятайте, що гіпертекст не обов’язково має бути HTML (або XML чи JSON) у браузері. Машини можуть переходити за посиланнями, якщо розуміють формат даних і типи зв’язків.

Приклад

Розглянемо наступні дані і порівняємо згідно правил REST, це публікація в блозі з посиланнями на відповідні ресурси в REST API на основі HTTP. Тут міститься необхідна інформація про публікацію в блозі, а також гіпермедійні посилання на відповідні ресурси, такі як автор і коментарі. Клієнти можуть перейти за цими посиланнями, щоб знайти додаткову інформацію або виконати дії.

{
  "id": 123,
  "title": "What is REST",
  "content": "REST is an architectural style for building web services...",
  "published_at": "2023-11-04T14:30:00Z",
  "author": {
    "id": 456,
    "name": "John Doe",
    "profile_url": "https://example.com/authors/johndoe"
  },
  "comments": {
    "count": 5,
    "comments_url": "https://example.com/posts/123/comments"
  },
  "self": {
    "link": "https://example.com/posts/123"
  }
}

request structure & methods (ч.1)

Що таке HTTP?

Hypertext Transfer Protocol – Протокол передачі гіпертексту (HTTP) призначений для забезпечення зв’язку між клієнтами та серверами.

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

Веб-браузер може бути клієнтом, а додаток на комп’ютері, на якому розміщений вебсайт, може бути сервером.

Приклад: клієнт (браузер) відправляє HTTP-запит на сервер; потім сервер повертає відповідь клієнту. Відповідь містить інформацію про стан запиту і може також містити запитуваний контент.

Структура реквесту (api request)

endpoint (кінцева точка на яку відправляється запит) складається з (URI) Uniform Resource Identifier, який вказує, де і як знайти ресурс в Інтернеті. Найпоширенішим типом URI є унікальне розташування ресурсу (URL), яке служить повною веб-адресою і використувається в більшості апікальній побудованих по правилах REST.

Headers (хедери) зберігають інформацію, актуальну як для клієнта, так і для сервера. В основному заголовки містять дані автентифікації, такі як ключ API, ім’я або IP-адреса комп’ютера, на якому встановлено сервер, і інформацію про формат відповіді.

body (тіло) використовується для передачі додаткової інформації на сервер. Наприклад, це може бути частина даних, яку ви хочете додати або замінити.

HTTP Методи

GET
POST
PUT
HEAD
DELETE
PATCH
OPTIONS

Метод GET

GET використовується для запиту даних від вказаного ресурсу.

GET – один із найбільш розповсюджених методів HTTP.

Зверніть увагу, що рядок запиту (пари ім’я/значення) відправляється в URL-адресі запиту GET: /v2/pet/findByStatus?status=available

Деякі інші зауваження про запити GET:

GET-запити можуть бути кешовані
GET-запити залишаються в історії браузера
GET-запити можуть бути додані в закладки
GET-запити ніколи не повинні використовуватись при роботі з конфіденційними даними.
GET-запити мають обмеження по довжині
GET-запити використовуються тільки для запиту даних (не змінюються)

curl -X 'GET' \\
  '<https://petstore.swagger.io/v2/pet/findByStatus?status=available>' \\
  -H 'accept: application/json'

Метод POST

POST використовується для надсилання даних на сервер для створення/оновлення ресурсу.

POST є одним із найбільш розповсюджених методів HTTP.

Деякі інші зауваження про запити POST:

POST-запити ніколи не кешуються
POST-запити не зберігаються в історії браузера
POST-запити не можуть бути додані в закладки
POST-запити не мають обмежень по довжині даних

curl -X 'POST' \
  'https://petstore.swagger.io/v2/pet' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}'

Метод PUT

PUT використовується для надсилання даних на сервер для створення/оновлення ресурсу.

Різниця між POST та PUT полягає в тому, що PUT-запити є ідентичними. Тобто, виклик одного і того ж запиту PUT кілька разів завжди буде призводити до одного й того ж результату. Напроти, виклик POST-запиту неодноразово має побічні ефекти від створення одного й того ж ресурсу кілька разів.

curl -X 'PUT' \
  'https://petstore.swagger.io/v2/pet' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}'

Метод HEAD

HEAD майже ідентичний GET, але без тіла відповіді.

Іншими словами, якщо GET/користувачі повертає список користувачів, то HEAD/користувачі зробить такий самий запит, але не поверне список користувачів.

Запити HEAD корисні для перевірки того, що буде повернуто запит GET, перед тим, як фактично виконати запит GET, наприклад, перед завантаженням великого файлу або тіла відповіді. Використовується для перевірки роботи АПІ.

Метод DELETE

Метод DELETE видаляє вказаний ресурс.

curl -X 'DELETE' \\
  '<https://petstore.swagger.io/v2/pet/23>' \\
  -H 'accept: application/json' \\
  -H 'api_key: my_key'

Метод PATCH

Використовується для часткового оновлення даних

curl -X 'PATCH' \
  'https://petstore.swagger.io/v2/pet' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "status": "available"
}'

Метод OPTIONS

Метод OPTIONS описує параметри зв’язку для цільового ресурсу.

Структура запиту Щоб отримати доступ до ресурсу, клієнт надсилає HTTP-запит. Натомість сервер генерує HTTP-відповідь із закодованими даними на ресурсі. Обидва типи повідомлень REST є описовими, тобто містять інформацію про те, як їх інтерпретувати та обробляти. Методи REST API і структура запиту

Будь-який запит REST включає чотири основні частини: метод HTTP, кінцеву точку, заголовки та тіло.

Метод HTTP описує, що потрібно зробити з ресурсом. Існує чотири основні методи, які також називаються операціями CRUD: POST для створення ресурсу, GET, щоб отримати ресурс, PUT для оновлення ресурсу та DELETE, щоб видалити ресурс. Уніфікований ідентифікатор ресурсу (URI), який вказує, де і як знайти ресурс в Інтернеті. Найпоширенішим типом URI є унікальне розташування ресурсу (URL), яке служить повною веб-адресою.

Хедери зберігають інформацію, актуальну як для клієнта, так і для сервера. В основному хедери містять дані автентифікації, такі як ключ API, ім’я або IP-адреса комп’ютера, на якому встановлено сервер, і інформацію про формат відповіді.

Тіло (body) використовується для передачі додаткової інформації на сервер. Наприклад, це може бути частина даних, яку ви хочете додати або замінити.

response structure

Структура респонсу (відповіді)

У відповідь сервер надсилає не сам шуканий ресурс, а його представлення (representation) — код для машини і опис його поточного стану. Один і той же ресурс може бути представлений у різних форматах, але найпопулярнішими є XML і JSON.

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

Приклад респонсу на запит PUT який є в прикладі вище

{
  "page": 1,
  "per_page": 12,
  "total": 12,
  "total_pages": 1,
  "data": [
    {
      "id": 1,
      "name": "cerulean",
      "year": 2000,
      "color": "#98B2D1",
      "pantone_value": "15-4020"
    },
    {
      "id": 2,
      "name": "fuchsia rose",
      "year": 2001,
      "color": "#C74375",
      "pantone_value": "17-2031"
    },
    {
      "id": 3,
      "name": "true red",
      "year": 2002,
      "color": "#BF1932",
      "pantone_value": "19-1664"
    },
    {
      "id": 4,
      "name": "aqua sky",
      "year": 2003,
      "color": "#7BC4C4",
      "pantone_value": "14-4811"
    },
    {
      "id": 5,
      "name": "tigerlily",
      "year": 2004,
      "color": "#E2583E",
      "pantone_value": "17-1456"
    },
    {
      "id": 6,
      "name": "blue turquoise",
      "year": 2005,
      "color": "#53B0AE",
      "pantone_value": "15-5217"
    },
    {
      "id": 7,
      "name": "sand dollar",
      "year": 2006,
      "color": "#DECDBE",
      "pantone_value": "13-1106"
    },
    {
      "id": 8,
      "name": "chili pepper",
      "year": 2007,
      "color": "#9B1B30",
      "pantone_value": "19-1557"
    },
    {
      "id": 9,
      "name": "blue iris",
      "year": 2008,
      "color": "#5A5B9F",
      "pantone_value": "18-3943"
    },
    {
      "id": 10,
      "name": "mimosa",
      "year": 2009,
      "color": "#F0C05A",
      "pantone_value": "14-0848"
    },
    {
      "id": 11,
      "name": "turquoise",
      "year": 2010,
      "color": "#45B5AA",
      "pantone_value": "15-5519"
    },
    {
      "id": 12,
      "name": "honeysuckle",
      "year": 2011,
      "color": "#D94F70",
      "pantone_value": "18-2120"
    }
  ],
  "support": {
    "url": "https://reqres.in/#support-heading",
    "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
  }
}

status codes

Коди статусу відповіді HTTP вказують на те, чи успішно виконано конкретний запит HTTP. Відповіді згруповані в п’ять класів:

Informational responses (100 – 199)
Successful responses (200 – 299)
Redirection messages (300 – 399)
Client error responses (400 – 499)
Server error responses (500 – 599)

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

Інформаційні відповіді Informational responses (100 – 199) 100 Continue (Продовжити) Ця проміжна відповідь вказує на те, що клієнт повинен продовжити запит або проігнорувати відповідь, якщо запит уже виконано.

101 Switching Protocols (Протоколи комутації) Цей код надсилається у відповідь на заголовок запиту на оновлення від клієнта та вказує на протокол, на який перемикається сервер.

Успішні відповіді Successful responses (200 – 299) 200 OK (Добре) Запит виконано. Значення результату “успіх” залежить від методу HTTP:

GET: ресурс було отримано та передано в тілі повідомлення. HEAD: Заголовки подання включені у відповідь без будь-якого тіла повідомлення. PUT або POST: ресурс, що описує результат дії, передається в тілі повідомлення. TRACE: тіло повідомлення містить повідомлення запиту, отримане сервером. 201 Created (Створено) Запит виконано успішно, і в результаті створено новий ресурс. Зазвичай це відповідь, що надсилається після запитів POST або деяких запитів PUT.

Повідомлення перенаправлення Redirection messages (300 – 399) 300 Multiple Choices Запит має більше ніж одну можливу відповідь. Агент користувача або користувач повинні вибрати один із них. (Немає стандартизованого способу вибору однієї з відповідей, але рекомендовано HTML-посилання на можливості, щоб користувач міг вибрати.)

301 Moved Permanently (Переїхав) URL запитуваного ресурсу змінено назавжди. Нова URL-адреса вказана у відповіді.

Відповіді клієнта на помилки Client error responses (400 – 499) 400 Bad Request (Поганий запит) Сервер не може або не хоче обробити запит через щось, що сприймається як помилка клієнта (наприклад, неправильний синтаксис запиту, недійсний кадр повідомлення запиту або оманлива маршрутизація запиту).

401 Unauthorized (Несанкціонований) Хоча стандарт HTTP визначає «неавторизований», семантично ця відповідь означає «неавтентифікований». Тобто клієнт повинен пройти автентифікацію, щоб отримати запитану відповідь.

402 Payment Required Experimental (Вимагається оплата) Цей код відповіді зарезервовано для використання в майбутньому. Початковою метою створення цього коду було використання його для цифрових платіжних систем, однак цей код статусу використовується дуже рідко, і стандартної угоди не існує.

403 Forbidden (Заборонено) Клієнт не має прав доступу до контенту; тобто він неавторизований, тому сервер відмовляється надати запитуваний ресурс. На відміну від 401 Unauthorized, особа клієнта відома серверу.

404 Not Found (Не знайдено) Сервер не може знайти запитуваний ресурс. У браузері це означає, що URL-адреса не розпізнається. В API це також може означати, що кінцева точка дійсна, але сам ресурс не існує. Сервери також можуть надсилати цю відповідь замість 403 Forbidden, щоб приховати існування ресурсу від неавторизованого клієнта. Цей код відповіді, мабуть, найвідоміший через те, що він часто зустрічається в Інтернеті.

Помилки сервера Server error responses (500 – 599) 500 Internal Server Error (Внутрішня помилка сервера) Сервер зіткнувся з ситуацією, з якою він не знає, як впоратися.

501 Not Implemented (Не реалізовано) Метод запиту не підтримується сервером і не може бути оброблений. Єдиними методами, які повинні підтримувати сервери (і тому вони не повинні повертати цей код), є GET і HEAD.

502 Bad Gateway (Поганий шлюз) Ця відповідь про помилку означає, що сервер, працюючи як шлюз для отримання відповіді, необхідної для обробки запиту, отримав недійсну відповідь.

503 Service Unavailable (Служба недоступна) Сервер не готовий обробити запит. Поширеними причинами є сервер, який не працює на технічне обслуговування або перевантажений. Зауважте, що разом із цією відповіддю слід надіслати зручну сторінку з поясненням проблеми. Цю відповідь слід використовувати для тимчасових умов, а HTTP-заголовок Retry-After має, якщо можливо, містити приблизний час до відновлення служби. Веб-майстер також повинен подбати про заголовки, пов’язані з кешуванням, які надсилаються разом із цією відповіддю, оскільки ці тимчасові відповіді умов зазвичай не слід кешувати.

504 Gateway Timeout (Час очікування шлюзу) Ця відповідь про помилку надається, коли сервер діє як шлюз і не може вчасно отримати відповідь.

documentation & API Versioning

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

Що таке Swagger?

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

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

Swagger оброблячі API проекту повертає YAML або JSON файл, що містить детальний опис усього API. Цей файл по суті є списком ресурсів вашого API, який відповідає специфікації OpenAPI. І потім цей документ зберігається в депо або надається інструкція по генерації документації для використання API.

❗Swagger не єдиний інструмент для документації API – але найбільш популярний.

лінк на документацію сваггеру

https://petstore.swagger.io/#/pet/updatePet

Керування версіями API (API Versioning)

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

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

api.mysite/v1/customers

Потім коли команда додає нові зміни, розширює функціонал API – просто додаємо URL-адресу, яка розширює клас контролера v1, і отримуємо щось на зразок цього:

api.mysite/v2/customers

Де нова версія доступна за цифрою 2

За допомогою такого підходу створюються нові версії свого API без необхідності видаляти попередні версії свого API.

API

<it/>Praktik

API тестування