284 lines
8.8 KiB
Markdown
284 lines
8.8 KiB
Markdown
# p1ctos4ve - контракты API
|
||
|
||
## Better Auth
|
||
API использует фреймворк [Better Auth](https://better-auth.com) для управления пользователями и сессиями.
|
||
|
||
Для работы с авторизацией необходимо использовать [клиентскую библиотеку](https://www.better-auth.com/docs/concepts/client) Better Auth, прямой вызов методов авторизации из клиентов не предусматривается.
|
||
|
||
### `POST /auth/api/sign-up/email`
|
||
|
||
Регистрация нового пользователя с почтой и паролем.
|
||
|
||
**Параметры запроса:**
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"email": "string",
|
||
"password": "string",
|
||
"image": "string (опционально)",
|
||
"callbackURL": "string (опционально)",
|
||
"rememberMe": "boolean (опционально, по умолчанию true)"
|
||
}
|
||
```
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"token": "string | null",
|
||
"user": {
|
||
"id": "string",
|
||
"email": "string",
|
||
"name": "string",
|
||
"image": "string | null",
|
||
"emailVerified": "boolean",
|
||
"createdAt": "string (date-time)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
}
|
||
```
|
||
|
||
### `POST /auth/api/sign-in/email`
|
||
|
||
Вход с использованием почты и пароля.
|
||
|
||
**Параметры запроса:**
|
||
```json
|
||
{
|
||
"email": "string",
|
||
"password": "string",
|
||
"callbackURL": "string (опционально)",
|
||
"rememberMe": "string (опционально)"
|
||
}
|
||
```
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"redirect": false,
|
||
"token": "string",
|
||
"url": null,
|
||
"user": {
|
||
"id": "string",
|
||
"email": "string",
|
||
"name": "string | null",
|
||
"image": "string | null",
|
||
"emailVerified": "boolean",
|
||
"createdAt": "string (date-time)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
}
|
||
```
|
||
|
||
### `POST /auth/api/sign-out`
|
||
|
||
Выход из системы и завершение текущей сессии.
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"success": "boolean"
|
||
}
|
||
```
|
||
|
||
## Сейвы
|
||
API для работы с сохраненными медиафайлами (видео, фото). Каждый сейв имеет настройку видимости, определяющую режим доступа.
|
||
|
||
### Режимы видимости сейва
|
||
- `public` - сейв доступен всем пользователям, отображается в публичных списках и профиле владельца
|
||
- `link` - сейв доступен только по прямой ссылке (shareUrl), не отображается в публичных списках. Владелец всегда видит его в своих списках
|
||
|
||
### `GET /saves/my`
|
||
|
||
Возвращает все сейвы текущего пользователя независимо от режима видимости.
|
||
|
||
**Аутентификация:** Опциональна
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
[
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"description": "string",
|
||
"tags": ["string"],
|
||
"visibility": "public" | "link",
|
||
"shareUrl": "string (только для visibility: link)",
|
||
"createdAt": "string (date-time)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
]
|
||
```
|
||
|
||
### `GET /saves/u/{slug}`
|
||
Возвращает **только публичные сейвы** (visibility: public) конкретного пользователя по его никнейму (slug). Сейвы с видимостью "link" не включаются в этот список, даже если запрашивает владелец.
|
||
|
||
**Параметры пути:**
|
||
- `slug` (string, обязательный) - никнейм пользователя
|
||
|
||
**Аутентификация:** Опциональна
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
[
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"description": "string",
|
||
"tags": ["string"],
|
||
"visibility": "public",
|
||
"createdAt": "string (date-time)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
]
|
||
```
|
||
|
||
### `GET /saves/{id}`
|
||
Возвращает информацию о конкретном сейве.
|
||
|
||
**Параметры пути:**
|
||
- `id` (number/string, обязательный) - ID сейва
|
||
|
||
**Аутентификация:** Опциональна
|
||
|
||
**Правила доступа:**
|
||
- **Владелец:** полный доступ ко всем сейвам (public и link)
|
||
- **Другие пользователи:**
|
||
- **public сейвы:** доступны всем
|
||
- **link сейвы:** доступны только при обращении по корректной shareUrl; запрос по голому ID вернет `404 Not Found`
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"description": "string",
|
||
"tags": ["string"],
|
||
"visibility": "public" | "link",
|
||
"shareUrl": "string (только для visibility: link)",
|
||
"userId": "string",
|
||
"createdAt": "string (date-time)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
```
|
||
|
||
**Коды ошибок:**
|
||
- `404 Not Found` - сейв не найден или недоступен (для link сейвов без shareUrl)
|
||
- `403 Forbidden` - нет прав доступа
|
||
|
||
### `DELETE /saves/{id}`
|
||
Удаляет сейв по его ID. Доступно только владельцу.
|
||
|
||
**Параметры пути:**
|
||
- `id` (number/string, обязательный) - ID сейва
|
||
|
||
**Аутентификация:** Обязательна
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Сейв успешно удален"
|
||
}
|
||
```
|
||
|
||
### `PATCH /saves/{id}`
|
||
Обновляет метаданные сейва (название, описание, теги, видимость). Доступно только владельцу.
|
||
|
||
**Параметры пути:**
|
||
- `id` (number/string, обязательный) - ID сейва
|
||
|
||
**Параметры запроса:**
|
||
```json
|
||
{
|
||
"name": "string (опционально)",
|
||
"description": "string (опционально)",
|
||
"tags": ["string"] (опционально),
|
||
"visibility": "public" | "link" (опционально)
|
||
}
|
||
```
|
||
|
||
**Аутентификация:** Обязательна
|
||
|
||
**Content-Type:** `application/json`, `application/x-www-form-urlencoded`, или `multipart/form-data`
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"description": "string",
|
||
"tags": ["string"],
|
||
"visibility": "public" | "link",
|
||
"shareUrl": "string (если visibility: link)",
|
||
"updatedAt": "string (date-time)"
|
||
}
|
||
```
|
||
|
||
**Примечание:** При установке `visibility: "link"` сервер автоматически генерирует или возвращает существующую `shareUrl`. При смене на `visibility: "public"` поле `shareUrl` становится неактуальным.
|
||
|
||
### `POST /saves/external`
|
||
Скачивает и сохраняет медиафайл по URL из стороннего источника.
|
||
|
||
**Параметры запроса:**
|
||
```json
|
||
{
|
||
"url": "string (URI, обязательный)",
|
||
"name": "string (опционально)",
|
||
"description": "string (опционально)",
|
||
"tags": ["string"] (опционально),
|
||
"visibility": "public" | "link" (опционально, по умолчанию: link)"
|
||
}
|
||
```
|
||
|
||
**Аутентификация:** Обязательна
|
||
|
||
**Content-Type:** `application/json`, `application/x-www-form-urlencoded`, или `multipart/form-data`
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"url": "string",
|
||
"visibility": "public" | "link",
|
||
"shareUrl": "string (если visibility: link)",
|
||
"createdAt": "string (date-time)"
|
||
}
|
||
```
|
||
|
||
Если `visibility` не указана, по умолчанию устанавливается `link`.
|
||
|
||
### `POST /saves/upload`
|
||
Загружает медиафайл с устройства.
|
||
|
||
**Параметры запроса (multipart/form-data):**
|
||
- `file` (`binary`, обязательный) - файл для загрузки
|
||
- `name` (`string`, опционально) - название сейва
|
||
- `description` (`string`, опционально) - описание сейва
|
||
- `tags` (`array[string]`, опционально) - теги
|
||
- `visibility` (`"public" | "link"`, опционально, по умолчанию: "link") - режим видимости
|
||
|
||
**Аутентификация:** Обязательна
|
||
|
||
**Content-Type:** `multipart/form-data`
|
||
|
||
**Ответ (200):**
|
||
```json
|
||
{
|
||
"id": "number",
|
||
"name": "string",
|
||
"type": "string",
|
||
"url": "string",
|
||
"visibility": "public" | "link",
|
||
"shareUrl": "string (если visibility: link)",
|
||
"createdAt": "string (date-time)"
|
||
}
|
||
```
|
||
|
||
Если `visibility` не указана, по умолчанию устанавливается `link`.
|