Использование curl для HTTP: GET, POST, PUT, DELETE

Введение

HTTP — основной протокол передачи данных в интернете. Для взаимодействия с веб-сервисами используются методы GET, POST, PUT, DELETE и другие. curl — кроссплатформенный инструмент командной строки, который позволяет легко отправлять такие запросы и отлаживать API.

Коротко: curl полезен для разработчиков, тестировщиков, администраторов и инженеров DevOps. Он работает в терминале, не требует графического интерфейса и подходит для автоматизации.

Установка и проверка curl

curl уже установлен в большинстве Linux, macOS и Unix-систем. Чтобы убедиться, что curl доступен, выполните:

curl --version

Команда выведет версию curl и поддерживаемые протоколы. Если curl отсутствует, скачайте его с официальной страницы загрузок curl.

Важно: на Windows можно использовать встроенный curl в PowerShell (Windows 10+) или установить Git Bash / WSL для более привычного поведения Unix-версии.

Базовый принцип: метод, URL, заголовки и тело

HTTP-запрос состоит из:

• метода (GET, POST, PUT, DELETE, PATCH и т.д.);
• URL;
• заголовков (headers) — например, Content-Type или Authorization;
• необязательного тела (payload) для POST/PUT/PATCH.

curl по умолчанию делает GET-запрос, если явно не указан другой метод.

GET: получить ресурс

GET используется для запроса данных с сервера. Пример:

curl https://example.com/todos/1

Альтернатива с указанием метода (необязательно):

curl -X GET https://example.com/todos/1

Полезные опции при GET:

• ‘-i’ — вывести заголовки ответа вместе с телом;
• ‘-I’ — отправить HEAD-запрос и показать только заголовки;
• ‘-L’ — следовать переадресациям (redirects);
• ‘-o filename’ — сохранить ответ в файл;
• ‘-s’ — тихий режим (silent), часто используется с ‘–show-error’.

Пример сохранения и разбора JSON с jq:

curl -s https://example.com/todos/1 -o response.json
jq '.' response.json

POST: отправить данные

POST обычно применяют для создания ресурса или отправки формы. Данные передаются в теле запроса.

Пример формы с полями:

curl -X POST -d 'name=jack' -d 'email=jack@example.com' https://example.com/users

Объединённая форма:

curl -d 'name=jack&email=jack@example.com' https://example.com/api/users

Отправка JSON (указываем Content-Type):

curl -H 'Content-Type: application/json' -d '{"name":"Jack","email":"jack@example.com"}' https://example.com/api/users

Отправка данных из файла:

curl -d @users.txt https://example.com/api/users

Загрузка файла в форме multipart/form-data (например, изображение):

curl -F 'avatar=@/path/to/photo.jpg' https://example.com/api/upload

Пояснение: использование ‘-d’ по умолчанию устанавливает Content-Type: application/x-www-form-urlencoded. Для JSON указывайте явно ‘Content-Type: application/json’. Для загрузки файлов используйте ‘-F’ (multipart/form-data).

PUT и PATCH: обновление ресурсов

PUT применяется для замены или создания ресурса по указанному URL и является идемпотентным: повторный запрос с теми же данными не изменит результат дальше первого вызова. PATCH частично обновляет ресурс и обычно не идемпотентен по своему эффекту.

Пример PUT с JSON:

curl -X PUT -H 'Content-Type: application/json' -d '{"name":"Jack Bauer","email":"jackbauer024@example.com"}' https://example.com/api/users/4

Пример PATCH:

curl -X PATCH -H 'Content-Type: application/json' -d '{"email":"new@example.com"}' https://example.com/api/users/4

Выбирайте PUT, если заменяете весь ресурс; PATCH — если обновляете отдельные поля.

DELETE: удалить ресурс

DELETE удаляет ресурс по URL. Пример:

curl -X DELETE https://example.com/api/users/3

Если нужен заголовок авторизации:

curl -X DELETE -H 'Authorization: Bearer my_access_token' https://example.com/api/users/3

Также распространён Basic auth:

curl -u 'username:password' -X DELETE https://example.com/api/users/3

Будьте осторожны: DELETE часто требует аутентификации и прав, а удаление может быть необратимым.

Полезные флаги и отладка

• ‘-v’ — подробный вывод (verbose) для отладки TLS/handshake/заголовков;
• ‘–trace’ и ‘–trace-ascii’ — расширенная трассировка;
• ‘–max-time N’ — ограничение времени выполнения в секундах;
• ‘–connect-timeout N’ — таймаут установки соединения;
• ‘–insecure’ или ‘-k’ — игнорировать проверки сертификата (только для тестирования);
• ‘–compressed’ — запрос с поддержкой сжатия (gzip);
• ‘–http1.1’ / ‘–http2’ — принудительный выбор версии протокола;
• ‘-H’ — добавить произвольный заголовок;
• ‘-I’ — HEAD-запрос (полезно проверить заголовки без тела).

Пример: следовать редиректам, показать заголовки и сохранить тело:

curl -L -i https://example.com/path -o saved_response.txt

Типичные ошибки и как их исправить

1. Ошибка аутентификации 401/403 — проверьте токен, срок его действия и формат заголовка Authorization.
2. Неправильный Content-Type — сервер может отвергнуть JSON, если не указан ‘application/json’.
3. Переадресации — curl по умолчанию не следует редиректам; используйте ‘-L’.
4. SSL/TLS ошибки — на тестовом окружении можно временно ‘-k’, но в проде устраняйте причину (сертификаты, цепочку доверия).
5. Большие файлы не загружаются — используйте ‘–upload-file’ или ‘-F’ для multipart, проверьте ограничения сервера.

Чек-листы по ролям

Для разработчика:

• проверил метод и URL;
• указал правильный Content-Type;
• проверил ответный статус (2xx/4xx/5xx);
• сохранил тело ответа для логов.

Для тестировщика:

• воспроизвел запрос с curl в изолированном терминале;
• проверил поведение при повторных запросах (идемпотентность);
• проверил граничные и некорректные данные;
• проверил обработку ошибок и коды статусов.

Для администратора/DevOps:

• проверил таймауты и поведение при отказе;
• проверил сертификаты TLS;
• настроил логирование и мониторинг для API.

Критерии приёмки

• Запрос возвращает ожидаемый HTTP-статус (например, 200/201/204) для корректного сценария.
• Тело ответа содержит ожидаемые поля и валидный JSON, если это указано в API.
• Для операций создания возвращается идентификатор ресурса или Location-заголовок.
• Для удаления ресурс больше недоступен (404 по запросу GET).

Шпаргалка команд curl (быстро)

• GET: curl ‘https://example.com/resource’
• GET с заголовками: curl -i ‘https://example.com/resource’
• POST форма: curl -d ‘a=1&b=2’ ‘https://example.com/submit’
• POST JSON: curl -H ‘Content-Type: application/json’ -d ‘{“k”:”v”}’ ‘https://example.com’
• PUT: curl -X PUT -H ‘Content-Type: application/json’ -d ‘{“k”:”v”}’ ‘https://example.com/1’
• DELETE: curl -X DELETE ‘https://example.com/1’
• Файл в форме: curl -F ‘file=@/path/to/file’ ‘https://example.com/upload’
• Сохранить ответ: curl -o out.json ‘https://example.com’

Безопасность и приватность

• Никогда не храните реальные токены в публичных скриптах или репозиториях.
• Используйте HTTPS всегда; проверяйте сертификаты.
• Для автоматизации используйте секретное хранилище (vault, CI secrets), а не переменные в репозитории.
• При отладке на локальной машине используйте временные тестовые токены.

Когда не стоит использовать curl

• Для сложных сценариев тестирования API с графическим сравниванием откликов удобнее GUI-инструменты (Postman, Insomnia).
• Для браузерной отладки, где важны cookies, JavaScript и рендеринг, curl не заменит браузер.
• Если нужно визуально оценивать страницы и ресурсы — используйте браузер или headless браузеры.

Playbook: быстрая отладка API с curl

1. Проверить доступность: curl -I URL
2. Выполнить запрос и посмотреть заголовки: curl -i URL
3. Включить подробный вывод: curl -v URL
4. Сохранить тело и проанализировать: curl -s URL -o resp.json && jq ‘.’ resp.json
5. Повторить с необходимыми заголовками и телом: curl -H ‘Authorization: Bearer …’ -H ‘Content-Type: application/json’ -d ‘{“k”:”v”}’ URL
6. Проверить поведение при таймауте: curl –max-time 5 URL

Краткая справка по кодам ответа

• 2xx — успех (200 OK, 201 Created, 204 No Content)
• 3xx — перенаправление (следуйте с ‘-L’)
• 4xx — ошибка клиента (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found)
• 5xx — ошибка сервера (500 Internal Server Error)

Эти значения стандартны для HTTP; в каждом API могут быть дополнительные нюансы.

Заключение

curl остаётся универсальным инструментом для отправки HTTP-запросов и отладки API. Он подходит для одноразовых запросов в терминале, автоматизации и интеграции в скрипты. Изучите полезные флаги, безопасно храните секреты и используйте правильные Content-Type и методы для каждой операции.

Важно: практика и чтение ответа сервера подскажут, какие дополнительные флаги и подходы нужны в конкретном случае.