curl: HTTP-запросы (GET, POST, PUT, DELETE)

Ноутбук с кодом в текстовом редакторе в двух колонках.

Что такое curl и зачем он нужен

curl — это утилита командной строки для передачи данных с помощью URL-схем (обычно HTTP/HTTPS). Она полезна для быстрого отладки API, автоматизации запросов и тестирования сетевых сценариев. Ключевая идея: curl формирует HTTP-запрос и выводит ответ сервера в консоль.

Краткое определение терминов:

HTTP: протокол передачи гипертекста, стандарт для веб-коммуникаций.
Метод HTTP (GET/POST/PUT/DELETE и т. д.): указывает намерение запроса.
Заголовок (header): метаданные запроса/ответа (например, Content-Type, Authorization).
Тело (body/payload): данные запроса (для POST/PUT).

Установка curl

На macOS, большинстве дистрибутивов Linux и Unix curl обычно уже установлен. Проверьте это командой:

curl

Если curl установлен, терминал предложит “try ‘curl –help’ or ‘curl –manual’ for more information”. Если утилита отсутствует — установите её через пакетный менеджер вашей ОС или с официальной страницы загрузок curl.

Важно: используйте актуальную версию curl, особенно если вам нужны современные TLS-алгоритмы.

Общие советы по безопасности

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

Примечание: при тестировании с реальными сервисами сначала используйте тестовые учётные записи и среду разработки.

HTTP GET — получение ресурса

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

Пример с явным указанием метода:

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

Тот же запрос без флага -X:

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

Когда использовать: получение страниц, JSON-объектов, изображений и т. п. Не используйте GET для чувствительных данных — они могут попасть в логи и историю браузера.

Критерии приёмки для GET:

Код ответа: 200 (или 304 для кеширования).
Тело содержит ожидаемые поля/данные.
Заголовок Content-Type соответствует ожидаемому формату.

HTTP POST — отправка данных (создание)

POST отправляет данные в теле запроса. Обычно используется для создания ресурсов.

Базовый синтаксис:

curl -X POST -d

Пример формы x-www-form-urlencoded:

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

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

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

Указание Content-Type (JSON):

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

Если вы отправляете бинарные данные или файлы, используйте multipart/form-data:

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

Когда POST не подходит: когда операция идемпотентна (например, обновление) — тогда лучше PUT или PATCH.

HTTP PUT — обновление или создание (идемпотентный)

PUT обычно обновляет ресурс полностью. Если ресурс отсутствует, сервер иногда создаст его.

Пример JSON-обновления:

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

Преимущества PUT: повторный вызов с одинаковыми данными не меняет результат (идемпотентность). Для частичных обновлений чаще используют PATCH.

Критерии приёмки для PUT:

Код ответа: 200 или 204 (успех без тела) или 201 при создании.
Ресурс содержит новые значения.

HTTP DELETE — удаление ресурса

DELETE удаляет указанный ресурс. Запросы DELETE обычно требуют аутентификации и прав.

Пример:

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

Пример с авторизацией Bearer:

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

Важно: удаление может быть необратимым. Перед выполнением автоматически удаляющих операций сделайте бэкап или используйте режим подтверждения.

Частые флаги curl — шпаргалка

-X — явно задать HTTP-метод (GET, POST, PUT, DELETE и т. д.).
-d, –data — данные для тела запроса (формат x-www-form-urlencoded по умолчанию).
-F, –form — для multipart/form-data (загрузка файлов).
-H, –header
— добавить/переопределить HTTP-заголовок.
-I, –head — получить только заголовки ответа (HEAD-запрос).
-i — вывести заголовки ответа вместе с телом.
-v — подробный вывод (debug).
-s — тихий режим (suppress progress).
-u — базовая авторизация (Basic Auth).
–compressed — запрос с поддержкой сжатия ответа (gzip).
-k, –insecure — отключить проверку TLS (небезопасно).

Пример с базовой авторизацией:

curl -u username:password https://example.com/secret

Пример получения только заголовков:

curl -I https://example.com

Работа с сертификатами и HTTPS

По умолчанию curl проверяет сертификат сервера. Не используйте -k в продакшене.
Для указания собственного сертификата клиента используйте –cert и –key.

Пример:

curl --cert client.pem --key client.key https://secure.example.com

Отладка и логирование

Для подробной отладки пользуйтесь -v или –trace-ascii для логов с метками:

curl -v https://example.com

Используйте -o или -O для сохранения ответа в файл:

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

-o — сохранить ответ в указанный файл.
-O — сохранить под оригинальным именем, указанным сервером.

Когда curl не подходит (контрпример)

Вам нужен графический интерфейс с инспектором запросов и визуализацией — используйте Postman или Insomnia.
Вы работаете с потоковыми данными в приложении — лучше использовать библиотеку HTTP в языке приложения (fetch, axios, requests).
Требуется сложная автоматизация в CI с обработкой HTTP-сессий и куки — рассмотрите специализированные тестовые фреймворки.

Альтернативные инструменты

Postman / Insomnia — GUI для тестирования API.
httpie — более человекочитаемый CLI-клиент.
fetch / axios / requests — библиотечные клиенты для приложений.

Ментальные модели и эвристики

Метод = намерение (GET — получить, POST — создать, PUT — заменить, PATCH — частично изменить, DELETE — удалить).
Заголовки — контракт между клиентом и сервером (Content-Type, Accept, Authorization).
Идемпотентность — повторение запроса не меняет результата (PUT, DELETE чаще идемпотентны; POST — нет).

Мини-методология: как правильно сформировать запрос с curl (5 шагов)

Определите метод (GET/POST/PUT/DELETE/PATCH).
Подготовьте URL и параметры (query string).
Подберите заголовки (Content-Type, Authorization и т. д.).
Подготовьте тело (JSON, form-data или файл).
Выполните запрос и проверьте код ответа и тело.

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

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

Есть локальный сервер/мок.
Тестовые данные подготовлены.
Используется Content-Type: application/json при отправке JSON.
Логи запросов ведутся и не содержат секретов.

Для QA:

Пишем тест-кейсы с проверкой кода ответа и схемы JSON.
Тестируем граничные условия и негативные сценарии.

Для системного администратора:

Проверяем TLS/сертификаты.
Ограничиваем доступ к секретам и логам.
Настроены правила бэкапа перед массовыми удалениями.

Тест-кейсы и критерии приёмки (пример)

Тест 1 — GET /todos/1:

Ожидание: код 200, Content-Type application/json, поле id == 1.

Тест 2 — POST /users (валидные данные):

Ожидание: код 201 или 200, в ответе есть id созданного пользователя.

Тест 3 — DELETE /users/3 (без авторизации):

Ожидание: код 401 или 403 (отказ).

Шаблоны команд (cheat sheet)

Получить ресурс:

curl https://example.com/resource

Отправить JSON:

curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' https://api.example.com/endpoint

Загрузить файл:

curl -F "file=@/path/to/file.jpg" https://api.example.com/upload

Удалить с токеном:

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.example.com/resource/123

Потоки ошибок и отладочные шаги

Смотрим код ответа: curl возвращает 0 при успехе, иначе ненулевой код.
Если TLS-ошибка — проверьте дату/время на машине и цепочку сертификатов.
Если получаете 4xx/5xx — посмотрите заголовки сервера через -i или -v.
Логи сервера часто содержат причину ошибки; используйте correlation-id, если он есть.

Decision flow (упрощённая схема)

flowchart TD
  A[Нужно получить/изменить ресурс?] --> B{Тип операции}
  B -->|Получить| C[GET]
  B -->|Создать| D[POST]
  B -->|Обновить| E[PUT или PATCH]
  B -->|Удалить| F[DELETE]
  C --> G[-- Выполнить curl]
  D --> G
  E --> G
  F --> G

Примеры практических сценариев

Получить только заголовки для проверки кеширования:

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

Отправить JSON из файла (payload.json):

curl -X POST -H "Content-Type: application/json" -d @payload.json https://api.example.com/submit

Отправить токен через заголовок Authorization:

export TOKEN="your_token_here"
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

Совместимость и миграционные примечания

curl доступен на большинстве платформ. При миграции сценариев из curl в библиотеку языка учтите поведение по умолчанию: перенаправления (-L), обработка куки и поведение по умолчанию для методов.

Краткое резюме

curl — быстрый и мощный инструмент для HTTP-запросов.
Используйте правильный метод HTTP и заголовок Content-Type.
Храните секреты безопасно и не передавайте их в логах.
Для сложной визуальной отладки используйте GUI-инструменты.

Важно: перед выполнением рискованных операций (многократное удаление, массовые обновления) протестируйте команды в тестовой среде или сделайте бэкап.

FAQ

Q: Можно ли отправлять JSON без Content-Type?
A: Сервер может принять JSON, но корректно указывать Content-Type: application/json обязательно.

Q: Как скрыть токен в истории команд?
A: Используйте переменные окружения или файлы с правами доступа 600; не вставляйте токен прямо в командную строку.

Q: Как повторять запросы при ошибках сети?
A: Используйте цикл в shell или опцию –retry для curl, например –retry 3.

Быстрый справочник: как делать HTTP-запросы с помощью curl