cURL: анатомия команд и конвертация в код

В документации к каждому API есть примеры кода. Почти всегда они написаны на cURL — HTTP-клиенте командной строки, поставляемом в каждой Unix-подобной системе и являющемся общим языком API-документации уже несколько десятилетий. Проблема в том, что вы пишете не shell-скрипты, а код на JavaScript, Python, Go или Ruby — и прежде чем использовать команду, вам нужно перевести её в рабочий код на нужном языке.

Этот перевод утомителен и чреват ошибками. Заголовки, схемы аутентификации, тела запросов и URL-кодирование — всё это нужно отобразить на правильные вызовы методов в правильном языке. Конвертер cURL BrowseryTools делает это автоматически — вставьте команду cURL и получите эквивалентный код на JavaScript fetch, Python requests, Node.js axios и других языках. Бесплатно, без регистрации, всё остаётся в браузере.

Что такое cURL?

cURL (Client URL) — инструмент командной строки для передачи данных с использованием URL. Он поддерживает HTTP, HTTPS, FTP, WebSockets и десятки других протоколов. Для разработчиков он чаще всего используется для HTTP-запросов из терминала — тестирования API-эндпоинта, загрузки файла или отладки аутентификации.

cURL установлен по умолчанию в macOS и большинстве дистрибутивов Linux. В Windows он поставляется вместе с ОС начиная с Windows 10. Именно эта повсеместность объясняет, почему команды, пишущие документацию к API, выбирают cURL для примеров — они могут быть уверены, что любой разработчик, читающий документацию, сможет немедленно запустить пример без каких-либо установок.

Анатомия команды cURL

Команда cURL состоит из базового URL и набора флагов. Вот полный пример, охватывающий наиболее важные флаги:

curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Разбор каждого флага:

• -X POST — задаёт HTTP-метод. Допустимые значения: GET, POST, PUT, PATCH, DELETE и др. Если флаг опущен, но присутствует -d, cURL по умолчанию использует POST.
• -H "Header: Value" — добавляет заголовок запроса. Можно указывать несколько раз для нескольких заголовков.
• -d '...' — тело запроса. Для JSON используйте совместно с -H "Content-Type: application/json". По умолчанию cURL URL-кодирует тело, если не использован --data-raw.
• --data-raw '...' — отправляет тело как есть, без URL-кодирования. Необходим, когда тело содержит символы вроде @, которые -d интерпретировал бы особым образом.
• -u username:password — сокращение для базовой аутентификации. cURL самостоятельно кодирует их как заголовок Authorization в Base64.
• -s — тихий режим; скрывает индикатор прогресса. Почти всегда используется в скриптах.
• -v — подробный режим; выводит заголовки запроса и ответа. Незаменим при отладке проблем аутентификации.
• -o filename — записывает вывод в файл вместо stdout.

Типичные паттерны cURL для REST API

GET-запрос с параметрами запроса

curl "https://api.example.com/users?page=2&limit=20" \
  -H "Authorization: Bearer TOKEN"

Параметры запроса указываются прямо в URL. Заключайте весь URL в кавычки, чтобы shell не интерпретировал символ & как оператор фонового процесса.

POST с телом JSON

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  --data-raw '{"product_id": 42, "quantity": 3}'

Загрузка файла (multipart/form-data)

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "description=Q4 Report"

Флаг -F отправляет multipart/form-data. Префикс @ означает «читать из файла». Этот формат используется для загрузки изображений, API обработки документов и любых эндпоинтов, принимающих бинарные данные.

Конвертация cURL в JavaScript fetch

// Original cURL:
// curl -X POST https://api.example.com/v1/users \
//   -H "Content-Type: application/json" \
//   -H "Authorization: Bearer TOKEN" \
//   -d '{"name": "Alice", "email": "alice@example.com"}'

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer TOKEN",
  },
  body: JSON.stringify({
    name: "Alice",
    email: "alice@example.com",
  }),
});

const data = await response.json();

Конвертация cURL в Python requests

import requests

response = requests.post(
    "https://api.example.com/v1/users",
    headers={
        "Authorization": "Bearer TOKEN",
    },
    json={
        "name": "Alice",
        "email": "alice@example.com",
    },
)

data = response.json()

Параметр json= библиотеки requests автоматически обрабатывает как сериализацию, так и установку заголовка Content-Type: application/json — задавать его вручную не нужно.

Конвертация cURL в Node.js с axios

const axios = require("axios");

const response = await axios.post(
  "https://api.example.com/v1/users",
  {
    name: "Alice",
    email: "alice@example.com",
  },
  {
    headers: {
      Authorization: "Bearer TOKEN",
    },
  }
);

const data = response.data;

Как работает «Copy as cURL» в DevTools браузера

Одна из наиболее полезных функций DevTools браузера — «Copy as cURL» («Скопировать как cURL»). В Chrome, Firefox или Safari: откройте DevTools, перейдите на вкладку Network, выполните запрос (войдите в систему, нажмите кнопку, загрузите страницу), щёлкните правой кнопкой мыши по запросу в списке и выберите «Copy as cURL».

Браузер генерирует полную команду cURL, включающую каждый заголовок, который он отправил, — в том числе куки, токены сессии, CSRF-токены и любые другие данные аутентификации. Это значит, что вы можете воспроизвести тот же запрос, который браузер сделал — включая весь его контекст аутентификации — из терминала или кода.

Это незаменимо при отладке: если браузерный запрос работает, а запрос из вашего кода нет, вставьте оба в инструмент сравнения и найдите различие в заголовке или теле. Скопированный cURL также можно вставить напрямую в Конвертер cURL BrowseryTools и получить эквивалентный код на нужном языке — конвертер автоматически обрабатывает экранирование, кавычки и перевод флагов.

Итоги

cURL — универсальный язык HTTP. Документация API использует его, потому что каждый может его запустить. DevTools копирует его, потому что он захватывает каждую деталь запроса. Умение читать cURL свободно — и точно переводить его на любой язык, с которым вы работаете, — это практический навык, который окупается при каждой интеграции нового API. Пропустите утомительный ручной перевод и используйте Конвертер cURL BrowseryTools — получайте чистый, готовый к запуску код за секунды.