quoter/docs/api-reference.md

# API Reference

## Обзор

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

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

## Базовый 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>
```

**Ответ:**
```json
{
  "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](./vercel-og-integration.md).

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

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

**Параметры запроса:**
- `user_id` - ID пользователя

**Пример:**
```
GET /quota?user_id=user123
```

**Ответ:**
```json
{
  "user_id": "user123",
  "current_quota": 1073741824,
  "max_quota": 5368709120
}
```

#### POST /quota/increase
Увеличивает квоту пользователя.

**Тело запроса:**
```json
{
  "user_id": "user123",
  "additional_bytes": 1073741824
}
```

**Ответ:**
```json
{
  "user_id": "user123",
  "current_quota": 2147483648,
  "max_quota": 5368709120
}
```

#### POST /quota/set
Устанавливает квоту пользователя.

**Тело запроса:**
```json
{
  "user_id": "user123",
  "new_quota_bytes": 2147483648
}
```

**Ответ:**
```json
{
  "user_id": "user123",
  "current_quota": 2147483648,
  "max_quota": 5368709120
}
```

## Коды ошибок

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

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

### Загрузка изображения
```bash
curl -X POST http://localhost:8080/ \
  -H "Authorization: Bearer your-token" \
  -F "file=@image.jpg"
```

### Получение информации о пользователе
```bash
curl -H "Authorization: Bearer your-token" \
     http://localhost:8080/
```

### Получение миниатюры
```bash
curl http://localhost:8080/image_300.jpg
```

### Увеличение квоты
```bash
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}'
```