Руководство по тестированию и отладке API: от cURL до онлайн-инструментов

Инструменты разработки

Методы HTTP-запросов

Метод Назначение Идемпотентный Безопасный
GET Получение ресурса ✅ ✅
POST Создание ресурса ❌ ❌
PUT Полное обновление ✅ ❌
PATCH Частичное обновление ❌ ❌
DELETE Удаление ресурса ✅ ❌
HEAD Получение заголовков ✅ ✅
OPTIONS Предзапрос CORS ✅ ✅

Часто используемые заголовки запроса

Заголовок Описание Пример
Content-Type Формат тела запроса application/json
Accept Ожидаемый формат ответа application/json
Authorization Информация аутентификации Bearer token...
User-Agent Идентификатор клиента Mozilla/5.0...
Cookie Cookie session=abc123
X-Request-ID ID отслеживания запроса UUID

Частые значения Content-Type

Значение Назначение
application/json Данные JSON
application/x-www-form-urlencoded Данные формы
multipart/form-data Загрузка файлов
text/plain Простой текст
text/html HTML

Методы аутентификации

1. Bearer Token (самый частый)

# cURL
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  https://api.example.com/users

# JavaScript
fetch('https://api.example.com/users', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...',
  },
});

2. Basic Auth

# cURL (автоматическое кодирование)
curl -u username:password https://api.example.com/users

# Ручное кодирование
# Base64("username:password") = "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/users

3. API Key

# Способ 1: Header
curl -H "X-API-Key: your-api-key" \
  https://api.example.com/users

# Способ 2: Параметр запроса
curl "https://api.example.com/users?api_key=your-api-key"

Подробно о команде cURL

Базовый GET-запрос

# Простейший GET
curl https://api.example.com/users

# Показать заголовки ответа
curl -i https://api.example.com/users

# Показать только заголовки ответа
curl -I https://api.example.com/users

# Следовать перенаправлениям
curl -L https://example.com/redirect

POST-запрос

# Данные JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Данные формы
curl -X POST https://api.example.com/users \
  -d "name=Alice&email=alice@example.com"

# Загрузка файла
curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=My photo"

Расширенные опции

# Настройка таймаута
curl --connect-timeout 5 --max-time 30 https://api.example.com

# Сохранить в файл
curl -o response.json https://api.example.com/users

# Тихий режим (без прогресс-бара)
curl -s https://api.example.com/users

# Подробный вывод (для отладки)
curl -v https://api.example.com/users

# Игнорировать проверку SSL-сертификата (только для разработки)
curl -k https://self-signed.example.com

# Прокси
curl -x http://proxy:8080 https://api.example.com

# Cookie
curl -b "session=abc123" https://api.example.com/users

# Сохранить и отправить Cookie
curl -c cookies.txt -b cookies.txt https://api.example.com/users

Частые коды состояния HTTP

Код Значение Частая причина
200 OK Успех
201 Created POST успешно создан
204 No Content DELETE выполнен
301 Moved Permanently Постоянное перенаправление
304 Not Modified Попадание в кэш
400 Bad Request Неверные параметры
401 Unauthorized Не аутентифицирован
403 Forbidden Нет прав
404 Not Found Ресурс не существует
409 Conflict Конфликт ресурса
422 Unprocessable Entity Ошибка валидации
429 Too Many Requests Ограничение частоты
500 Internal Server Error Ошибка сервера
502 Bad Gateway Upstream-сервис недоступен
503 Service Unavailable Сервис перегружен

Использование ToolsKu для тестирования API

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

  1. Открыть Инструмент cURL в код
  2. Вставить команду cURL
  3. Выбрать целевой язык (JavaScript/Python/Go/Java и т.д.)
  4. Скопировать сгенерированный код

Пример

# Ввод cURL
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "Alice"}'

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

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
  },
  body: JSON.stringify({ name: 'Alice' }),
});
const data = await response.json();

Техники отладки API

1. Просмотр полного запроса/ответа

# -v показывает подробную информацию
curl -v https://api.example.com/users

# Вывод:
> GET /users HTTP/1.1          ← Строка запроса
> Host: api.example.com        ← Заголовки запроса
> Authorization: Bearer ...
>
< HTTP/1.1 200 OK              ← Строка ответа
< Content-Type: application/json ← Заголовки ответа
< X-RateLimit-Remaining: 99
<
[{"id": 1, "name": "Alice"}]   ← Тело ответа

2. Форматирование JSON-ответа

# Форматирование с помощью jq
curl -s https://api.example.com/users | jq

# С помощью python
curl -s https://api.example.com/users | python -m json.tool

# Или используйте инструмент форматирования JSON от ToolsKu

3. Измерение времени ответа

# Подробная статистика времени
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.example.com/users

# Вывод:
# DNS: 0.012s
# Connect: 0.035s
# TTFB: 0.120s
# Total: 0.125s

4. Устранение проблем CORS

Ошибка браузера:
Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy

Шаги устранения:
1. Проверить предзапрос OPTIONS
   curl -X OPTIONS -H "Origin: https://app.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -i https://api.example.com/users

2. Проверить заголовки ответа
   Access-Control-Allow-Origin: https://app.example.com
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Max-Age: 86400

5. Устранение проблем аутентификации

Устранение 401 Unauthorized:
1. Токен истёк? → Использовать инструмент декодирования JWT для проверки exp
2. Формат токена верный? → Проверить префикс Bearer
3. Токен отправлен? → curl -v проверить заголовки запроса

Устранение 403 Forbidden:
1. Есть ли у пользователя права? → Проверить роль пользователя
2. IP в белом списке? → Проверить логи сервера
3. Превышен лимит частоты? → Проверить код состояния 429

Лучшие практики тестирования API

1. Управление переменными окружения

# Использовать переменные окружения для хранения конфиденциальных данных
export API_BASE="https://api.example.com"
export API_TOKEN="your-token"

curl -H "Authorization: Bearer $API_TOKEN" "$API_BASE/users"

2. Коллекция запросов

#!/bin/bash
# api-test.sh

BASE="https://api.example.com"
TOKEN="Bearer $API_TOKEN"
HEADER="-H 'Content-Type: application/json' -H 'Authorization: $TOKEN'"

# Получить список пользователей
get_users() { curl -s $HEADER "$BASE/users" | jq; }

# Создать пользователя
create_user() { curl -s -X POST $HEADER -d "$1" "$BASE/users" | jq; }

# Получить одного пользователя
get_user() { curl -s $HEADER "$BASE/users/$1" | jq; }

# Использование
get_users
create_user '{"name":"Bob"}'
get_user 1

3. Автоматизированные тесты

// Написание API-тестов с fetch
async function testApi() {
  // Тест GET
  const listRes = await fetch('/api/users');
  console.assert(listRes.status === 200, 'GET /users should return 200');

  // Тест POST
  const createRes = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Test' }),
  });
  console.assert(createRes.status === 201, 'POST /users should return 201');

  const created = await createRes.json();
  console.assert(created.name === 'Test', 'Name should match');
}

Часто задаваемые вопросы

Проблемы с кавычками cURL на Windows?

Windows CMD использует двойные кавычки, в PowerShell есть проблемы с экранированием:

# В PowerShell cURL — это псевдоним Invoke-WebRequest
# Используйте curl.exe для вызова настоящего cURL
curl.exe -X POST https://api.example.com/users `
  -H "Content-Type: application/json" `
  -d '{\"name\": \"Alice\"}'

Как устранить таймаут?

1. Медленный DNS? → curl -w проверить time_namelookup
2. Медленное соединение? → curl -w проверить time_connect
3. Медленная обработка сервером? → curl -w проверить time_starttransfer - time_connect
4. Медленная передача ответа? → curl -w проверить time_total - time_starttransfer

Заключение

Отладка API — повседневная задача разработчика: освоение команд cURL, кодов состояния HTTP, методов аутентификации и техник отладки позволяет быстро находить проблемы с интерфейсами. Инструмент cURL в код и Инструмент форматирования JSON от ToolsKu — отличные помощники в отладке API, помогающие быстро тестировать интерфейсы и просматривать ответы.

#API testing#HTTP requests#cURL#API debugging#tutorial