Как проверить доступность REST API

Проверить доступность REST API — значит убедиться не только в том, что сервер вернул какой-либо HTTP-ответ. Надёжная проверка последовательно подтверждает несколько уровней: DNS, соединение, TLS для HTTPS, HTTP-статус, допустимое время ответа и содержимое JSON.

200 OK доказывает успешность HTTP-запроса на уровне протокола, но не гарантирует, что API вернул правильные данные или выполнил бизнес-функцию.

Какие уровни нужно проверить

Полезная модель:

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

Для /health может быть достаточно успешного кода. Для API оплаты или профиля нужно проверять больше.

Базовая проверка через curl

curl -i https://api.example.com/health

-i добавляет response headers. В первой строке будет статус.

Только HTTP-код:

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

Здесь -sS отключает progress bar, -o /dev/null не выводит body, а -w печатает выбранные данные после выполнения.

Проверка времени ответа

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

time_total — полная длительность операции.

Заранее определите критерий, например:

HTTP 200
AND total < 2 секунды

Порог должен соответствовать реальному endpoint. Универсального timeout для всех API нет.

Подробная диагностика соединения

curl -v https://api.example.com/health

Verbose output помогает увидеть разрешённый IP, подключение, TLS, request headers и response headers.

Не публикуйте вывод вслепую: он может содержать Authorization, cookies и другие чувствительные данные.

Почему HTTP 200 недостаточно

API способен вернуть:

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

и одновременно:

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

HTTP-запрос завершён успешно, но фактический сервис неисправен.

Поэтому критерий должен соответствовать контракту:

HTTP == 200
AND Content-Type == JSON
AND $.status == "ok"

Как проверить JSON вручную

curl -sS https://api.example.com/health

Если установлен jq:

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

Получить конкретное поле:

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

Если контракт ожидает {"status":"ok"}, результат должен быть ok.

Почему простой pipeline curl | jq не всегда достаточен

Для диагностики важно разделять network error, HTTP error, невалидный JSON и неправильное поле.

Практичнее сначала сохранить body и HTTP-код:

tmp_file="$(mktemp)"

http_code="$(
  curl -sS \
    -o "$tmp_file" \
    -w '%{http_code}' \
    https://api.example.com/health
)"

Проверить HTTP:

if [ "$http_code" != "200" ]; then
  echo "HTTP error: $http_code"
  cat "$tmp_file"
  rm -f "$tmp_file"
  exit 1
fi

Затем JSON:

status="$(jq -r '.status // empty' "$tmp_file")"

if [ "$status" != "ok" ]; then
  echo "Unexpected API status: $status"
  rm -f "$tmp_file"
  exit 1
fi

rm -f "$tmp_file"

Так понятно, на каком уровне произошёл отказ.

Как ограничить максимальную длительность запроса

curl --max-time 5 \
  -i https://api.example.com/health

Пять секунд — только пример. Значение выбирают по реальному SLO endpoint.

Bearer Token

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

Не помещайте production token в документацию, репозиторий, скриншот или публичный чат. Для автоматизации используйте технические credentials с минимальными правами.

Basic Auth

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

Принцип тот же: секреты должны поступать из безопасного источника.

Проверка POST endpoint

curl -i \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"id":"test"}' \
  https://api.example.com/v1/check

Но нельзя бездумно использовать production-операцию, которая создаёт заказ, списывает деньги, отправляет письмо или меняет состояние пользователя.

Для synthetic monitoring нужен безопасный test endpoint, тестовый объект или idempotent сценарий.

Какие HTTP-коды считать успехом

Зависит от контракта:

• 200 — обычное успешное чтение;
• 201 — ресурс создан;
• 204 — успешно без body;
• 401 — ошибка, если монитор должен быть авторизован;
• 429 — запрос отклонён rate limit; для конкретной проверки это failure;
• 5xx — server-side error.

Правило «любой код меньше 500 — успех» слишком грубое.

Проверка Content-Type

curl -I https://api.example.com/health

Если endpoint обязан вернуть JSON, ожидайте подходящий Content-Type. Но заголовка недостаточно: важный ответ нужно реально парсить.

Проверка redirect

Без автоматического follow:

curl -i https://api.example.com/v1/data

С follow:

curl -iL https://api.example.com/v1/data

Для диагностики сначала полезнее не использовать -L, чтобы увидеть исходный код и Location.

Проверка DNS

dig api.example.com

или:

nslookup api.example.com

Проверьте, существует ли запись и соответствует ли IP ожидаемому.

Проверка TLS

openssl s_client \
  -connect api.example.com:443 \
  -servername api.example.com

-servername передаёт SNI. Если TLS не устанавливается, HTTP-код вообще не будет получен.

Как отличить недоступность API от ошибки клиента

Проверьте:

1. правильный ли URL;
2. правильный ли HTTP-метод;
3. нужный ли Content-Type;
4. корректна ли авторизация;
5. не истёк ли token;
6. не сработал ли rate limit;
7. воспроизводится ли проблема из другой сети;
8. что находится в server logs.

401 из-за просроченного token и 500 приложения — разные классы проблем.

Как выбрать endpoint для мониторинга

Хороший endpoint:

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

Плохая health check подтверждает только способность handler вернуть ответ.

Что мониторить кроме HTTP-кода

Для критичного API полезны availability, response time, HTTP status, JSON parse, обязательные поля, конкретное значение, auth и TLS отдельно.

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

Как обнаруживать проблемы автоматически

Ручной curl полезен при расследовании, но не сообщит, что API перестал работать ночью.

UpWatch можно использовать для регулярной проверки API endpoint. Если работоспособность определяется содержимым JSON, критерий должен соответствовать реальному контракту ответа, а не только коду 200.

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

Проверять только корень API-домена

GET / может возвращать 200, пока /v1/orders сломан.

Проверять только статус

Body может сообщать status=error.

Использовать опасный production POST

Мониторинг не должен создавать реальные заказы и платежи.

Хранить токен прямо в команде

Секрет может попасть в shell history или документацию.

Ставить слишком большой timeout

Если endpoint обычно отвечает за сотни миллисекунд, десятки секунд ожидания слишком поздно зафиксируют деградацию.

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

1. Выбрать endpoint, отражающий нужную функцию.
2. Проверить DNS.
3. Проверить TLS.
4. Зафиксировать ожидаемый HTTP-код.
5. Задать реалистичный timeout.
6. Проверить Content-Type.
7. Распарсить JSON.
8. Проверить обязательное поле/значение.
9. Корректно передать авторизацию.
10. Избегать операций с побочным эффектом.
11. Автоматизировать проверку.
12. Сохранять историю результатов.

Источники и спецификации

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