Skip to content

Latest commit

 

History

History
330 lines (245 loc) · 6.9 KB

API_EXAMPLES.md

File metadata and controls

330 lines (245 loc) · 6.9 KB

API Examples

🚀 Способы тестирования API

1. REST Client (VS Code) - Самый удобный! ⭐

Установи REST Client extension для VS Code.

Открой файл api.http и кликай кнопку "Send Request" над каждым запросом.

code api.http

Преимущества:

  • ✅ Клик мышкой - запрос выполнен
  • ✅ Видишь результаты прямо в редакторе
  • ✅ История запросов
  • ✅ Переменные окружения

2. Автоматический тест-скрипт

Запустит все эндпоинты последовательно:

chmod +x scripts/test_api.sh
./scripts/test_api.sh

Требования: jq для форматирования JSON

brew install jq  # macOS
apt install jq   # Ubuntu

3. curl команды

# Health Check
curl http://localhost:8000/health

# Создать пользователя
curl -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","name":"John Doe"}'

# Получить пользователя
curl http://localhost:8000/users/1

# Получить всех пользователей
curl http://localhost:8000/users/

# С форматированием через jq
curl http://localhost:8000/users/ | jq .

# Обновить пользователя
curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"John Updated"}'

# Удалить пользователя
curl -X DELETE http://localhost:8000/users/1

Больше примеров в файле: scripts/curl_examples.sh

4. HTTPie (более читаемая альтернатива curl)

Установка:

brew install httpie  # macOS
apt install httpie   # Ubuntu
pip install httpie   # любая ОС

Использование:

# GET запрос
http GET http://localhost:8000/users/

# POST запрос (проще чем curl!)
http POST http://localhost:8000/users/ email=john@example.com name="John Doe"

# PUT запрос
http PUT http://localhost:8000/users/1 name="Updated Name"

# DELETE запрос
http DELETE http://localhost:8000/users/1

5. Swagger UI (встроен в FastAPI)

Открой в браузере: http://localhost:8000/docs

  • ✅ Визуальный интерфейс
  • ✅ "Try it out" кнопка для каждого эндпоинта
  • ✅ Автоматическая документация
  • ✅ Примеры запросов/ответов

6. Python requests

import requests

BASE_URL = "http://localhost:8000"

response = requests.post(
    f"{BASE_URL}/users/",
    json={"email": "test@example.com", "name": "Test User"}
)
print(response.json())

user_id = response.json()["id"]

response = requests.get(f"{BASE_URL}/users/{user_id}")
print(response.json())

7. Docker (если используешь Docker)

# Запусти из контейнера
docker compose exec app curl http://localhost:8000/users/

# Или с хоста
curl http://localhost:8000/users/

📋 Примеры запросов

Health Check

curl http://localhost:8000/health

Ответ:

{"status":"ok"}

Создать пользователя

curl -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "name": "John Doe"
  }'

Ответ:

{
  "id": 1,
  "email": "john.doe@example.com",
  "name": "John Doe",
  "created_at": "2024-01-15T10:30:00",
  "updated_at": "2024-01-15T10:30:00"
}

Получить пользователя

curl http://localhost:8000/users/1

Получить всех пользователей

curl http://localhost:8000/users/

С пагинацией:

curl "http://localhost:8000/users/?limit=10&offset=0"

Обновить пользователя

curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "John Updated"}'

Можно обновлять частично:

# Только имя
curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name"}'

# Только email
curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com"}'

# Оба поля
curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com", "name": "New Name"}'

Удалить пользователя

curl -X DELETE http://localhost:8000/users/1

❌ Примеры ошибок

404 - Пользователь не найден

curl http://localhost:8000/users/999

Ответ:

{
  "detail": "User with id 999 not found"
}

409 - Дубликат email

curl -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{"email": "existing@example.com", "name": "Test"}'

Ответ:

{
  "detail": "User with email existing@example.com already exists"
}

422 - Невалидные данные

curl -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{"email": "not-an-email", "name": "Test"}'

Ответ:

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "email"],
      "msg": "value is not a valid email address"
    }
  ]
}

🎯 Рекомендации

Для разработки: REST Client в VS Code (api.http)
Для автоматизации: Скрипт test_api.sh
Для документации: Swagger UI (http://localhost:8000/docs)
Для интерактивной работы: HTTPie
Для CI/CD: curl в скриптах

💡 Полезные советы

Сохранить ID из ответа

USER_ID=$(curl -s -X POST http://localhost:8000/users/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"Test"}' | jq -r .id)

echo "Created user: $USER_ID"
curl http://localhost:8000/users/$USER_ID

Цикл создания пользователей

for i in {1..5}; do
  curl -X POST http://localhost:8000/users/ \
    -H "Content-Type: application/json" \
    -d "{\"email\":\"user$i@example.com\",\"name\":\"User $i\"}"
done

Тестирование производительности

# Apache Bench
ab -n 1000 -c 10 http://localhost:8000/users/

# wrk
wrk -t4 -c100 -d30s http://localhost:8000/users/

Готово! Выбирай любой удобный способ! 🚀