Как мониторить API endpoint

Мониторинг API endpoint должен отвечать на конкретный вопрос: может ли внешний клиент сейчас выполнить нужный запрос и получить ожидаемый результат. Проверять только TCP-соединение или любой HTTP 200 недостаточно, если работоспособность определяется JSON, авторизацией или конкретной зависимостью.

Хороший API-monitor строится как контракт: endpoint + метод + authentication + допустимое время + ожидаемый HTTP-код + при необходимости проверка response body.

Что именно должен проверять API-monitor

Базовая цепочка:

DNS → TCP/TLS → HTTP method → status → latency → JSON → бизнес-критерий

Чем критичнее endpoint, тем важнее заранее определить, на каком уровне результат считается успешным.

Шаг 1. Выберите правильный endpoint

Плохой выбор:

GET /

если реальная проблема пользователей возникает в:

GET /v1/orders

или:

POST /v1/checkout/validate

Хороший endpoint для регулярной проверки:

• имеет стабильный контракт;
• безопасен при повторном вызове;
• отражает критичную функцию;
• не создаёт реальные заказы/платежи;
• работает достаточно быстро;
• не возвращает «200 всегда» независимо от состояния.

Health endpoint или реальный API?

/health полезен, если он действительно отражает нужную готовность. Но слишком простой handler может отвечать 200 даже при недоступной БД.

Поэтому часто нужны два уровня:

/health         → базовая доступность приложения
/v1/critical    → реальная критичная функция

Не превращайте health endpoint в тяжёлую транзакцию со всеми зависимостями без необходимости — это само по себе создаёт нагрузку и каскадные эффекты.

Шаг 2. Зафиксируйте ожидаемый HTTP-код

Пример:

curl -sS -o /dev/null \
  -w '%{http_code}\n' \
  https://api.example.com/health

Если контракт ожидает 200, то 204 или 302 не должны автоматически считаться успехом только потому, что это не 5xx.

Для конкретного endpoint ожидаемым может быть 201 или 204. Монитор должен следовать контракту, а не универсальному правилу «любой 2xx/3xx подходит».

Шаг 3. Ограничьте допустимую длительность

curl --max-time 5 \
  -sS -o /dev/null \
  -w 'code=%{http_code} total=%{time_total}s\n' \
  https://api.example.com/health

Пять секунд здесь только пример. Порог выбирают по реальному SLO и нормальной latency endpoint.

Если API обычно отвечает за 200–300 мс, ждать десятки секунд перед фиксацией проблемы может быть слишком поздно.

Шаг 4. Проверяйте JSON, если он определяет здоровье

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "error",
  "database": "unavailable"
}

не должен считаться успешным только из-за 200.

Пример ручной проверки:

curl -sS https://api.example.com/health | jq -r '.status'

Ожидаемое значение:

ok

Подробнее об уровнях ручной проверки: как проверить доступность REST API.

Шаг 5. Выберите минимальный бизнес-критерий

Не проверяйте случайные динамические поля, изменение которых нормально.

Лучше:

$.status == "ok"

чем:

$.generated_at == конкретное значение

Критерий должен отличать отказ от нормального изменения данных.

Шаг 6. Решите вопрос с авторизацией

Bearer Token:

curl -i \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/v1/profile

Basic Auth:

curl -i \
  -u "$API_USER:$API_PASSWORD" \
  https://api.example.com/private/health

Для мониторинга используйте отдельные технические credentials:

• с минимальными правами;
• не принадлежащие конкретному сотруднику;
• с управляемым сроком жизни;
• хранящиеся как секрет.

Если credentials истекли, monitor получит 401. Это нужно уметь отличать от недоступности самого API.

Шаг 7. Не используйте опасный POST

Плохой synthetic monitor:

POST /orders → создаёт настоящий заказ каждые 60 секунд

Варианты безопаснее:

• idempotent GET;
• специальный read-only endpoint;
• тестовый tenant;
• dry-run/validate operation;
• контролируемый synthetic object с очисткой, если без state change не обойтись.

Нельзя считать регулярный побочный эффект нормальной ценой мониторинга.

Шаг 8. Выберите частоту проверки

Интервал зависит от:

• критичности API;
• допустимого времени обнаружения;
• стоимости запроса;
• rate limits;
• нагрузки;
• внешних квот.

Проверять дорогой endpoint каждую минуту может быть хуже, чем использовать лёгкую проверку чаще, а глубокий synthetic test — реже.

Шаг 9. Определите правило инцидента

Одна ошибка не всегда равна инциденту. Возможна краткая network anomaly точки мониторинга.

Но и слишком длинное подтверждение задерживает обнаружение.

Политика может учитывать:

несколько последовательных failures
или
подтверждение из другой точки

Точное правило выбирают по цене false positive и late detection.

Шаг 10. Сохраняйте данные, полезные для расследования

Для каждой проверки полезны:

• timestamp;
• endpoint;
• method;
• HTTP status;
• total time;
• тип network/TLS error;
• безопасный фрагмент результата проверки JSON;
• request ID, если доступен.

Не сохраняйте секретный Authorization header целиком.

Что делать при 5xx

Если monitor получает 500/502/503/504:

1. зафиксируйте первый timestamp;
2. проверьте масштаб;
3. сопоставьте request ID;
4. откройте gateway/application logs;
5. проверьте зависимости;
6. сравните latency перед отказом.

Связанные материалы: 500 Internal Server Error, 503 Service Unavailable и 504 Gateway Timeout.

Что делать при 401/403

Это не обязательно «API упал».

• 401 — проверьте технические credentials и auth flow;
• 403 — проверьте scopes/permissions/WAF policy.

Если monitor использует неправильный token, исправление приложения не требуется.

Отдельно контролируйте latency

API может не падать полностью, а деградировать:

200 за 200 мс → 200 за 2 с → 200 за 8 с → 504

Поэтому история response time помогает увидеть проблему до полного отказа.

Как проверить конфигурацию монитора вручную

До автоматизации воспроизведите тот же запрос curl:

curl -sS \
  -H "Authorization: Bearer $API_TOKEN" \
  -o response.json \
  -w 'code=%{http_code} total=%{time_total}s\n' \
  https://api.example.com/v1/health

Затем:

jq -r '.status' response.json

Если ручной критерий неоднозначен, автоматический monitor тоже будет ненадёжным.

Как проверить восстановление API

После исправления выполните серию запросов:

for i in {1..20}; do
  curl -sS -o /dev/null \
    -w '%{http_code} %{time_total}\n' \
    https://api.example.com/health
  sleep 1
done

Для JSON-проверки повторите и содержательный критерий. Один 200 не доказывает, что все backend-инстансы восстановлены.

UpWatch и API endpoint

UpWatch можно использовать для регулярной проверки API. Критерий должен соответствовать реальной задаче: ожидаемый HTTP-ответ, допустимое время и, когда это необходимо, содержимое JSON.

Мониторинг должен фиксировать симптом, а server-side logs и tracing — объяснять причину.

Типичные ошибки

Мониторить только /

Корень домена может работать независимо от API.

Считать любой 200 успехом

Body способен содержать application error.

Использовать production credentials сотрудника

Их отзыв или увольнение человека неожиданно ломает монитор.

Делать destructive POST

Проверка не должна создавать реальные бизнес-операции.

Выбирать слишком большой timeout

Деградация обнаруживается слишком поздно.

Проверять слишком много полей JSON

Монитор начинает падать из-за нормальных изменений ответа.

Практический чек-лист

1. Выбрать критичный и безопасный endpoint.
2. Зафиксировать method.
3. Зафиксировать ожидаемый HTTP status.
4. Задать допустимый timeout.
5. Проверить JSON при необходимости.
6. Выбрать устойчивый business criterion.
7. Настроить безопасные credentials.
8. Учесть rate limits и стоимость запроса.
9. Определить правило инцидента.
10. Сохранять историю status/latency.
11. Проверить alert на 401/403 отдельно от 5xx.
12. После сбоя подтверждать восстановление серией проверок.

Источники и документация

• RFC 9110: HTTP Semantics
• curl: официальная документация