chore: Описание технических требований в README
This commit is contained in:
283
assets/API.md
Normal file
283
assets/API.md
Normal file
@ -0,0 +1,283 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user