Моніторинг API

Чому API потребує власного моніторингу

API — це не просто сторінка під /api/. Це контракт. Метод HTTP має значення — GET vs POST змінює семантику. Заголовки несуть автентифікацію, content negotiation, ключі ідемпотентності. Тіло запиту — це вхід. Код відповіді має значення (401 vs 403 vs 422 — кожен говорить іншу історію). Тіло відповіді має структуру — JSON-шляхи, на які покладаються інтегратори. Звичайна перевірка uptime, яка просто викликає URL через GET, пропускає більшість способів, якими API може впасти: некоректний JSON, який все ще повертає 200, endpoint автентифікації, що приймає неправильні дані, webhook із зіпсованою схемою payload, endpoint, який повертає 200, але всередині "status": "error".

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

Конфігурація запиту

Для кожного монітора API в DiagnoSEO Моніторинг Доступності ти можеш налаштувати:

• Метод HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Обери той, який використовують інтегратори.
• Власні заголовки: як об'єкт JSON, наприклад {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Стандарт для тестування OAuth, JWT, API ключів, content negotiation.
• Тіло запиту: будь-який рядок — JSON, XML, form-encoded, plain text. Відправляється при POST/PUT/PATCH/DELETE.
• Basic auth: ім'я користувача та пароль, якщо endpoint так захищений.
• Очікувані коди статусу: список або діапазон. За замовчуванням 200-399, але можна звузити до одного коду (наприклад, точно 201 для endpoint створення) або дозволити конкретні (наприклад, 200,202,204).

Перевірка слідує максимум за 5 редіректами, декодує gzip, парсить Content-Type, щоб виявити JSON. Кожна перевірка записує фактичний код, час відповіді, розмір і можливу помилку. Декілька підряд невдач (налаштовується, за замовчуванням 2) викликають інцидент.

Асерції JSON path

Самих кодів статусу недостатньо для багатьох API. Endpoint health може повернути 200 з тілом {"status": "degraded", "db": "down"} — все ще 200, але тобі критично треба це знати. API цін може повернути 200 з тілом, де data.price знизилась до null. API пошукача може повернути 200 з results: [], бо індекс впав.

Для таких випадків налаштуй асерцію JSON path. Вкажи шлях (наприклад, data.status або health.checks.db) і очікуване значення (наприклад, healthy, true або конкретне число). При кожній перевірці відповідь декодується з JSON, а значення за шляхом порівнюється. Неспівпадіння закінчує перевірку аварією, незалежно від статусу HTTP.

Синтаксис шляху — крапкова нотація з дужками: data.items[0].id працює, так само users.john.email. Значення для асерції порівнюється як рядок, тож "true" підходить до bool true, а числа співпадають і як рядки і як числа.

Варіанти автентифікації

Два найпоширеніші стилі авторизації працюють одразу з коробки. Для токенів Bearer (OAuth, JWT, API ключі) використовуй поле headers: {"Authorization": "Bearer eyJhbGciOi..."}. Токен зберігається в налаштуваннях монітора і відправляється при кожній перевірці. Для basic auth використовуй спеціальні поля користувача/пароля — вони зберігаються та об'єднуються у стандартний заголовок.

Якщо авторизація вимагає підпису для кожного запиту або оновлення токена, це складніше. Два розумних варіанти: (1) налаштувати довгоживучий токен сервіс-аккаунта спеціально для моніторингу, або (2) створити endpoint health без автентифікації, який відображає стан справжнього захищеного, і моніторити його. Більшість сучасних API вже це мають із коробки.

Рекомендовані практики

• Один монітор на критичний endpoint. Не тестуй кожний — обери 5-10, невдача яких призведе до реальної шкоди.
• Використовуй точні коди. Типовий 200-399 занадто ліберальний для API. Endpoint створення має повертати точно 201; ідемпотентний — точно 200; endpoint логіну — точно 200 (успіх) або 401 (коректна відмова, а не 500).
• Комбінуй статус із JSON-асерцією. Разом вони ловлять регресії транспортного та контентного рівня. Сам статус не знайде помилок контенту, одна JSON-асерція крихка при редіректах.
• Вкажи поріг часу відповіді. Деградація API — рання ознака проблем із залежностями. Монітор з rt_threshold_ms = 800 сигналізує, що API сповільнюється ще до краху.
• Тримай тіло запиту малим. Перевірка запускається щохвилини — великі тіла марнують трафік з обох сторін. Достатньо представницьких, але мінімальних payload-ів.

Комбінуй із іншими типами моніторів

Для кожного endpoint API монітор API перевіряє, що виклик працює. Окремий пінг-монітор або порт-монітор перевіряє, чи сервер живий. Перевірка SSL/домену на цій же назві хоста ловить проблеми з сертифікатом і реєстрацією. DNS підмонітор слідкує за зміною записів, які можуть свідчити про підміну. Разом чотири монітори на API дають повну картину при мінімальному перетині.

Налаштування

Відкрий інструмент, натисни "Додати монітор", обери тип "API". Встав URL. Відкрий секцію Розширені. Обери метод, встав заголовки у вигляді JSON, встав тіло, якщо потрібно, налаштуй basic auth, якщо використовуєш, введи очікувані коди (наприклад, 200 або 200,201). Додай асерцію JSON path, якщо потрібно. Вкажи інтервал і поріг підтвердження. Збережи. З наступного циклу монітор викликає твоє API саме так, як зробив би інтегратор, перевіряє відповідь і сповіщає про регресію за секунду.

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

• Які методи HTTP я можу використовувати для моніторингу API?

  GET, POST, PUT, DELETE, PATCH та HEAD. Налаштовуй метод окремо для кожного монітора — для write-endpoint (POST/PUT/PATCH) тіло запиту теж конфігурується як JSON-рядок або form data.

• Як працюють асерції JSON?

  Вказуєш шлях JSON (наприклад, data.status або results[0].id) і очікуване значення. Монітор отримує відповідь, розбирає її як JSON, витягує шлях і порівнює з очікуваним. Якщо не співпадає, перевірка фейлить із помилкою "assertion failed", показуючи фактичне значення.

• Чи можу я відправляти заголовки автентифікації?

  Так. Кастомні HTTP-заголовки налаштовуються окремо для кожного монітора — токени Authorization, API-ключі, content-type, будь-що. Значення заголовків зашифровані на сервері. Для Basic Auth є спеціальне поле username/password, яке автоматично підписує запит.

• Що, якщо моє API повертає 200 з помилковим payload?

  Типова ситуація: API повертає HTTP 200, але тіло містить {"status":"error"}. Примітивний монітор uptime думає, що це нормально. Використай JSON-асерцію status == "ok" щоб це упіймати — асерція фейлить, і монітор повідомляє DOWN, навіть якщо HTTP повернув 200.

• Як моніторити API з rate limit?

  Встанови інтервал перевірок з урахуванням ліміту API (наприклад, 5-хвилинний інтервал, якщо API дозволяє 12 викликів/годину). Один чек рахується як один виклик API з одного регіону. Мультирегіональні чеки множать кількість викликів — використовуй один регіон, якщо твоє API має жорсткі ліміти.