Как проверить API через curl

curl позволяет воспроизвести API-запрос без браузера и увидеть, что происходит на уровнях DNS/TLS/HTTP. Для диагностики важно зафиксировать метод, URL, headers, body, authentication, status code и время ответа так же, как их использует реальный клиент.

Хороший curl-запрос становится минимальным воспроизводимым примером: его можно повторить, сравнить между средами и сопоставить с server logs.

Самая простая проверка GET endpoint

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

-i включает response headers. Смотрите status, Content-Type и body.

HTTP 200 — только первый уровень. Если контракт требует JSON status=ok, проверяйте его отдельно.

Получить только HTTP-код

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

• -sS скрывает progress meter и сохраняет сообщения об ошибках;
• -o /dev/null не печатает body;
• -w выводит метрики transfer.

Команды в статье ориентированы на Unix-like shell.

Измерить время ответа

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

Подробно:

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n' \
  https://api.example.com/v1/health

Ограничить transfer timeout

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

Пять секунд — пример, а не универсальный threshold. Если curl завершился собственным timeout, server HTTP status может отсутствовать.

Проверить headers

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

-I/--head выполняет HEAD. Не заменяйте его механически на -X HEAD: официальная документация curl предупреждает, что --request меняет строку метода, но не всё поведение transfer.

POST с JSON

curl -i \
  -H 'Content-Type: application/json' \
  --data '{"name":"test","enabled":true}' \
  https://api.example.com/v1/items

--data делает POST и отправляет data. Мы явно задаём JSON media type.

JSON из файла

request.json:

{
  "name": "test",
  "enabled": true
}

curl -i \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  https://api.example.com/v1/items

--data-binary полезен, когда нужно передать содержимое файла без преобразования newline.

PUT, PATCH и DELETE

curl -i -X PUT \
  -H 'Content-Type: application/json' \
  --data '{"name":"updated"}' \
  https://api.example.com/v1/items/42

curl -i -X PATCH \
  -H 'Content-Type: application/json' \
  --data '{"name":"updated"}' \
  https://api.example.com/v1/items/42

curl -i -X DELETE https://api.example.com/v1/items/42

Не выполняйте destructive запросы на production, если они могут изменить реальные данные.

Bearer Token

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

Хранить token в environment безопаснее, чем вставлять его в публичную команду или документацию.

Связанный материал: ошибка 401 Unauthorized.

Basic Auth

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

Basic credentials для реальных секретов передавайте только поверх HTTPS.

Произвольный header

curl -i \
  -H 'X-Request-ID: manual-check-123' \
  -H 'Accept: application/json' \
  https://api.example.com/v1/items

Request ID полезен для корреляции, если инфраструктура действительно его прокидывает.

Подробный обмен через -v

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

Verbose output показывает отправленные и полученные headers и сведения о соединении. Но он может раскрыть Authorization и cookies — очищайте секреты перед передачей лога.

Redirect

Без follow:

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

С follow:

curl -iL https://api.example.com/old

Для state-changing запросов сначала изучите промежуточный status и Location.

Отделить DNS через --resolve

curl -i \
  --resolve api.example.com:443:203.0.113.10 \
  https://api.example.com/v1/health

Hostname сохраняется для Host/SNI, но соединение идёт на указанный IP.

TLS

curl по умолчанию проверяет certificate HTTPS. Не закрепляйте -k/--insecure в production scripts: он отключает certificate verification.

Отдельная проверка:

openssl s_client \
  -connect api.example.com:443 \
  -servername api.example.com \
  </dev/null

Сохранить body и вывести status

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

Затем:

jq . response.json

Проверить поле JSON

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

Если API возвращает 200, но .status равен error, простая HTTP-проверка пропустит application failure.

Связанный материал: как проверить доступность REST API.

HTTP status и exit code curl — не одно и то же

curl имеет собственный exit code. HTTP 404/500 сам по себе не обязательно превращает transfer в non-zero exit без соответствующих options. Для диагностики удобно явно выводить %{http_code} и сохранять body.

Повторяемый диагностический запрос

Фиксируйте:

method
exact URL
headers без секретов
body
expected status
expected JSON criterion
timeout

Это намного полезнее сообщения «curl тоже не работает».

Сравнить staging и production

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

Одинаковый request помогает локализовать различие environment/configuration.

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

for i in {1..20}; do
  curl -sS -o response.json \
    -w '%{http_code} %{time_total}\n' \
    https://api.example.com/v1/health
  jq -r '.status' response.json
  sleep 1
done

Если ответы различаются, проверьте load balancer и backend replicas.

От ручного curl к мониторингу

Сначала сформулируйте однозначный контракт:

GET /v1/health
status = 200
time < выбранного порога
JSON $.status = "ok"

После этого его можно переносить в регулярную проверку. UpWatch можно использовать для мониторинга API endpoint, если request безопасен и критерии соответствуют реальному контракту.

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

• помещать token в публичную команду;
• использовать -X без понимания;
• считать 200 достаточным;
• постоянно использовать -k;
• тестировать DELETE/POST на реальных данных;
• скрывать redirect через -L с самого начала.

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

1. Зафиксировать exact URL.
2. Выбрать method.
3. Добавить нужные headers.
4. Передать body.
5. Передать auth безопасно.
6. Получить headers/body.
7. Зафиксировать HTTP status.
8. Измерить timings.
9. Проверить JSON criterion.
10. Проверить redirect.
11. При необходимости использовать --resolve.
12. Не отключать TLS verification без причины.
13. После исправления повторить серию.
14. Перенести устойчивый критерий в мониторинг.

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

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