Лучшие практики отправки HTTP POST-запросов с помощью cURL

API — это нервная система современного программного обеспечения. Каждый разработчик, работающий с веб-сервисами, знает, что это правда. Но отправлять данные аккуратно и правильно в эти API? Вот где всё быстро становится запутанным. И здесь на сцену выходит cURL — недооценённый герой HTTP-запросов. Он мощный, гибкий, удобный в командной строке, и сегодня я покажу вам, как именно заставить его работать на вас.

Тестируете ли вы эндпоинт, автоматизируете запросы или отлаживаете сложную интеграцию — понимание HTTP POST-запросов с cURL может сэкономить вам часы разочарований. Давайте начнём.

HTTP POST-запросы 101

В отличие от GET-запросов, POST-запросы не вставляют ваши данные в URL. Они отправляют их безопасно в теле запроса. С cURL это просто:

curl -d "param1=value1&param2=value2" http://example.com/

Обратите внимание — -X POST не нужен. Когда вы используете -d, cURL автоматически переключается на POST.

Несколько параметров? Просто добавляйте их:

curl -d name=admin -d shoesize=12 http://example.com/

cURL объединяет их через амперсанд автоматически.

Большие наборы данных? Загружайте их прямо из файла:

curl -d @filename http://example.com/

Если файл содержит переводы строк, используйте --data-binary. А если данные начинаются с @, но это не файл, --data-raw предотвращает неверное истолкование cURL.

Как передавать данные в POST-запросах

Form-encoded данные

Самые простые POST-запросы используют form-encoded данные:

curl --data 'name=michael' http://example.com/my-form/

По умолчанию используется application/x-www-form-urlencoded. Просто.

JSON-данные

Большинство современных API работают с JSON. Здесь важны заголовки:

curl --header "Content-Type: application/json" \
     --request POST \
     --data '{"name":"michael","value":"123"}' \
     https://example.com/api/

Пользователям Windows следует следить за кавычками:

curl --header "Content-Type: application/json" \
     --data "{\"emailAddress\":\"user@example.com\"}" \
     https://example.com/api/

Большие JSON-пакеты? Загружайте их из файла:

curl --data @data.json --header "Content-Type: application/json" https://example.com/

Загрузка файлов и multipart-формы

Нужно отправить файлы? Используйте -F:

curl -F files=@1.txt https://example.com/api/

При необходимости указывайте MIME-типы:

curl -F 'file=@path/to/file.csv;type=text/csv' https://example.com/api/

Хотите сохранить переводы строк и форматирование? Используйте --data-binary:

curl --data-binary @1.txt https://example.com/api/

JSON проще с современным cURL

Если у вас cURL версии 7.82 или новее, --json упрощает работу. Вместо того чтобы управлять заголовками и --data-binary, просто:

curl --json '{"tool": "curl"}' https://example.com/

Он автоматически устанавливает Content-Type: application/json и Accept: application/json.

Из файлов тоже работает:

curl --json @data.json https://example.com/

Комбинируйте cURL с инструментами для JSON, такими как jq или jo, для более мощных рабочих процессов:

jo name=value | curl --json @- https://example.com/ | jq

Используйте -g, чтобы избежать глоббинга URL, если ваш JSON содержит фигурные или квадратные скобки.

Итог

cURL — это больше, чем инструмент командной строки. Он упрощает работу с API. От form-данных и JSON-запросов до загрузки файлов и особенностей платформ — он справляется со всем. Эти примеры — практические шаблоны, которые можно использовать сразу, делая POST-запросы проще.

С навыками работы с cURL ваш терминал превращается в площадку для тестирования API, новых эндпоинтов и интеграций. Вы сможете отлаживать быстрее, работать надёжнее и сосредоточиться на создании функций, которые действительно имеют значение.