docs

docs/api-reference.md

@@ -0,0 +1,169 @@
+# 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}'
+```