quoter/docs/api-reference.md

# API Reference

## Обзор

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

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

**Ошибки:**
- `401 Unauthorized` - неверный токен
- `413 Payload Too Large` - превышена квота
- `415 Unsupported Media Type` - неподдерживаемый тип файла

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

#### GET /{filename}
Получает файл по имени.

**Параметры запроса:**
- `s=<shout_id>` - добавляет оверлей с данными shout (только для изображений)

**Примеры:**
```
GET /image.jpg
GET /image.jpg?s=123
GET /image_300.jpg
GET /image_300.jpg/webp
```

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

#### 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 | Превышена квота |
| 415 | Неподдерживаемый тип файла |
| 500 | Внутренняя ошибка сервера |

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

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

### Получение миниатюры
```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}'
```