Мониторинг 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 дней →