quoter/docs/api-reference.md

API Reference

Обзор

Quoter предоставляет REST API для загрузки файлов, управления квотами и получения файлов с автоматической генерацией миниатюр.

🆕 Интеграция с @vercel/og: Quoter теперь оптимизирован для работы с библиотекой @vercel/og для генерации динамических OpenGraph изображений. Подробности см. в Vercel OG Integration Guide.

Базовый URL

http://localhost:8080

Аутентификация

Все API endpoints (кроме получения файлов) требуют аутентификации через заголовок Authorization:

Authorization: Bearer <your-jwt-token>

Endpoints

1. Проверка состояния сервера

GET /

Проверяет работоспособность сервера.

Ответ:

200 OK
ok

2. Загрузка файлов

POST /

Загружает файл в S3 хранилище.

Заголовки:

Authorization: Bearer <token>
Content-Type: multipart/form-data

Параметры:

• file - файл для загрузки

Ответ:

200 OK
filename.ext

Ошибки:

• 400 Bad Request - нет файлов или все файлы пустые
• 401 Unauthorized - неверный или отсутствующий токен
• 413 Payload Too Large - превышена квота пользователя или лимит размера файла
• 415 Unsupported Media Type - неподдерживаемый тип файла
• 500 Internal Server Error - ошибка загрузки в S3 или обновления квоты

3. Получение информации о текущем пользователе

GET /

Получает информацию о залогиненном пользователе с данными о квоте.

Заголовки:

Authorization: Bearer <token>

Ответ:

{
  "user_id": "user123",
  "username": "john_doe",
  "token_type": "session",
  "created_at": "1642248600",
  "last_activity": "1642335000",
  "auth_data": "{\"roles\": [\"user\"]}",
  "device_info": "{\"platform\": \"web\"}",
  "quota": {
    "current_quota": 1073741824,
    "max_quota": 5368709120,
    "usage_percentage": 20.0
  }
}

Ошибки:

• 401 Unauthorized - неверный или отсутствующий токен

4. Получение файлов

GET /{filename}

Получает файл по имени с автоматической генерацией миниатюр.

Примеры:

GET /image.jpg                    # Оригинальный файл
GET /image_300.jpg               # Миниатюра 300px ширины
GET /image_300.jpg/webp          # Миниатюра в формате WebP

🚫 Удаленные параметры (Legacy):

• s=<shout_id> - параметр для OpenGraph overlay больше не поддерживается
• Встроенная генерация text overlay теперь обрабатывается через @vercel/og

✅ Современная альтернатива: Для генерации OpenGraph изображений с текстом используйте интеграцию с @vercel/og. См. Vercel OG Integration Guide.

5. Управление квотами

GET /quota

Получает информацию о квоте пользователя.

Параметры запроса:

• user_id - ID пользователя

Пример:

GET /quota?user_id=user123

Ответ:

{
  "user_id": "user123",
  "current_quota": 1073741824,
  "max_quota": 5368709120
}

POST /quota/increase

Увеличивает квоту пользователя.

Тело запроса:

{
  "user_id": "user123",
  "additional_bytes": 1073741824
}

Ответ:

{
  "user_id": "user123",
  "current_quota": 2147483648,
  "max_quota": 5368709120
}

POST /quota/set

Устанавливает квоту пользователя.

Тело запроса:

{
  "user_id": "user123",
  "new_quota_bytes": 2147483648
}

Ответ:

{
  "user_id": "user123",
  "current_quota": 2147483648,
  "max_quota": 5368709120
}

Коды ошибок

Код	Описание
200	Успешный запрос
400	Неверные параметры запроса или нет файлов
401	Неавторизованный доступ
404	Файл не найден
413	Превышена квота пользователя или лимит размера файла (500 МБ)
415	Неподдерживаемый тип файла
500	Внутренняя ошибка сервера

Примеры использования

Загрузка изображения

curl -X POST http://localhost:8080/ \
  -H "Authorization: Bearer your-token" \
  -F "file=@image.jpg"

Получение информации о пользователе

curl -H "Authorization: Bearer your-token" \
     http://localhost:8080/

Получение миниатюры

curl http://localhost:8080/image_300.jpg

Увеличение квоты

curl -X POST http://localhost:8080/quota/increase \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user123", "additional_bytes": 1073741824}'