Моніторинг API: як перевіряти JSON-відповідь, а не лише HTTP 200

Коротко: JSON API може повернути HTTP 200 з тілом {"status":"error","message":"DB unavailable"} - моніторинг, який стежить лише за status code, оголошує «UP». Справжній моніторинг API перевіряє й вміст відповіді, а не лише HTTP-рівень.

Проблема: HTTP 200 != працюючий API

REST API conventions кажуть правильно використовувати status code (200 OK, 4xx client error, 5xx server error). На практиці:

• Деякі API завжди повертають 200, помилка в JSON body
• API gateway може трансформувати 5xx у 200 з error JSON
• Frontend BFF endpoint'и часто обгортають backends і повертають 200, якщо комунікація відбулася, навіть якщо backend впав
• GraphQL endpoint'и завжди повертають 200, errors у полі errors[]

З точки зору класичного моніторингу (HTTP status code) усе OK. З точки зору реального клієнта API зламаний.

Content matching: ключові слова

Найпростіше доповнення до HTTP-моніторингу - keyword match. Визначаєте рядок, який повинен бути у відповіді - якщо немає, alert.

Приклад для health check endpoint:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Keyword match на "status":"ok". Якщо DB впаде й endpoint поверне "status":"degraded", моніторинг зловить.

Negative matching: чого бути не повинно

Іноді корисніше перевірити, що певного рядка НЕМАЄ у відповіді:

• "error" - помилка в body
• "maintenance" - несподіваний maintenance mode
• "deprecated" - API endpoint став deprecated
• фрагменти SQL помилок: "SyntaxError", "undefined", "null pointer" - просочуються backend помилки

Розширені твердження - roadmap

Зіставлення за простим текстом має обмеження. Для серйозного моніторингу API підходять структуровані твердження над JSON-структурою (JSONPath-вирази) та багатокрокові синтетичні транзакції (login -> захищений ендпоінт -> logout).

Твердження JSONPath та багатокрокові синтетичні транзакції перебувають у roadmap ePulz.io, але наразі не реалізовані. Якщо вони потрібні сьогодні, комбінуйте HTTP-монітор ePulz.io з власним скриптом, який надсилає результат через монітор heartbeat (при збої просто не надсилайте heartbeat).

Аутентифікація в моніторингу

Моніторований endpoint часто вимагає auth. Варіанти:

• Bearer token в Authorization header - типово long-lived monitoring token без терміну (треба безпечно зберігати)
• API key у query параметрі - видно в логах, не бажано
• HMAC signature - timestamp + URL + body hash підписаний shared secret. Найбезпечніше.
• mTLS - client cert на боці моніторингу. Підходить для внутрішніх API.

Попередження безпеки: Для моніторингу створіть виділений account / token з мінімальними правами (read-only health endpoint, не admin token). Ротуйте token регулярно. Якщо monitoring service протече, не витече весь доступ до API.

Response time SLO

API response time такий же важливий, як HTTP-код. Клієнт з timeout 30 с не бачить різниці між «API повертає 200 за 25 с» і «API у timeout». З точки зору UX обидва погані.

Налаштуйте:

• Hard timeout - через 10-15 с моніторинг оголошує DOWN
• Soft threshold - response time між 500-2000 мс = warning (degraded performance)
• Trending alerts - alert, якщо 95-й перцентиль response time виросте на 50% за останні 24 г

Per-endpoint моніторинг

У великого API десятки endpoint'ів. Не моніторте лише /health - навіть він може брехати. Визначте 3-5 критичних endpoint'ів:

• Найбільш використовувані business operations (POST /api/orders, GET /api/dashboard)
• Read endpoint для cache hit (швидка відповідь)
• Write endpoint з DB roundtrip
• External integration endpoint (викликає третю сторону - детектує відмови залежностей)

Кожен моніторте окремо. Під час інциденту бачите точно, яка частина API впала.

Висновок

Моніторинг API не можна звести до HTTP status code. Якісний моніторинг комбінує status + content match + response time + per-endpoint гранулярність + authentication, щоб нагадувати реального клієнта - не лише HTTP-клієнта.

Моніторинг API з keyword match

Status code + keyword в контенті + response time + auth headers. Per-endpoint гранулярність.

Спробувати на 7 днів →