Initial commit: проект документации YARU

2026-09-29 09:55:06 +00:00 · 2026-03-01 17:32:45 +03:00
commit 243b5caf7e
860 changed files with 13239 additions and 0 deletions
@@ -0,0 +1,188 @@
+# API документация
+
+## REST API
+
+### Базовый URL
+```
+GET/POST /api/v1/...
+```
+
+### Endpoints
+
+#### Аутентификация
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| POST | `/oauth/token` | Получение JWT токена |
+| POST | `/api/v1/accounts` | Регистрация |
+| GET | `/api/v1/accounts/verify_credentials` | Текущий пользователь |
+
+#### Посты
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| GET | `/api/v1/statuses/:id` | Получить пост |
+| POST | `/api/v1/statuses` | Создать пост |
+| DELETE | `/api/v1/statuses/:id` | Удалить пост |
+| POST | `/api/v1/statuses/:id/like` | Лайк |
+| POST | `/api/v1/statuses/:id/reblog` | Репост |
+
+#### Ленты
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| GET | `/api/v1/timelines/home` | Домашняя лента |
+| GET | `/api/v1/timelines/public` | Публичная лента |
+| GET | `/api/v1/accounts/:id/statuses` | Посты пользователя |
+
+#### Подписки
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| GET | `/api/v1/accounts/:id/followers` | Подписчики |
+| GET | `/api/v1/accounts/:id/following` | Подписки |
+| POST | `/api/v1/accounts/:id/follow` | Подписаться |
+| POST | `/api/v1/accounts/:id/unfollow` | Отписаться |
+
+#### Карма
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| GET | `/api/v1/accounts/:id/karma` | Карма пользователя |
+| GET | `/api/v1/karma/history` | История кармы (текущий пользователь) |
+
+#### Экспорт
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| POST | `/api/v1/export` | Запрос экспорта данных |
+| GET | `/api/v1/export/:job_id` | Статус экспорта |
+| GET | `/api/v1/export/:job_id/download` | Скачивание архива |
+
+---
+
+## ActivityPub API
+
+### WebFinger
+```
+GET /.well-known/webfinger?resource=acct:{username}@{domain}
+```
+
+**Ответ**:
+```json
+{
+  "subject": "acct:username@yaru.nixg.ru",
+  "links": [
+    {
+      "rel": "self",
+      "type": "application/activity+json",
+      "href": "https://yaru.nixg.ru/users/username"
+    }
+  ]
+}
+```
+
+### Actor (Профиль пользователя)
+```
+GET /users/{username}
+```
+
+**Ответ** (ActivityPub Actor):
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://w3id.org/security/v1"
+  ],
+  "id": "https://yaru.nixg.ru/users/username",
+  "type": "Person",
+  "preferredUsername": "username",
+  "name": "Display Name",
+  "summary": "<p>Bio text</p>",
+  "inbox": "https://yaru.nixg.ru/users/username/inbox",
+  "outbox": "https://yaru.nixg.ru/users/username/outbox",
+  "followers": "https://yaru.nixg.ru/users/username/followers",
+  "following": "https://yaru.nixg.ru/users/username/following",
+  "publicKey": {
+    "id": "https://yaru.nixg.ru/users/username#main-key",
+    "owner": "https://yaru.nixg.ru/users/username",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----..."
+  }
+}
+```
+
+### Inbox (Входящие активности)
+```
+POST /users/{username}/inbox
+```
+
+**Принимаемые активности**:
+- `Follow` — запрос подписки
+- `Undo` — отмена подписки/лайка
+- `Create` — новый пост (от подписчиков)
+- `Like` — лайк поста
+- `Announce` — репост
+
+### Outbox (Исходящие активности)
+```
+GET /users/{username}/outbox
+```
+
+**Ответ**:
+```json
+{
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "id": "https://yaru.nixg.ru/users/username/outbox",
+  "type": "OrderedCollection",
+  "totalItems": 42,
+  "orderedItems": [
+    {
+      "id": "https://yaru.nixg.ru/statuses/123/activity",
+      "type": "Create",
+      "actor": "https://yaru.nixg.ru/users/username",
+      "object": { ... }
+    }
+  ]
+}
+```
+
+---
+
+## Формат ошибок
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Поле 'content' не может быть пустым",
+    "details": {
+      "field": "content",
+      "reason": "required"
+    }
+  }
+}
+```
+
+### Коды ошибок
+| Код | HTTP статус | Описание |
+|-----|-------------|----------|
+| `VALIDATION_ERROR` | 400 | Ошибка валидации |
+| `UNAUTHORIZED` | 401 | Не авторизован |
+| `FORBIDDEN` | 403 | Нет доступа |
+| `NOT_FOUND` | 404 | Ресурс не найден |
+| `RATE_LIMITED` | 429 | Превышен лимит |
+| `INTERNAL_ERROR` | 500 | Внутренняя ошибка |
+
+---
+
+## Rate Limiting
+
+| Endpoint | Лимит | Окно |
+|----------|-------|------|
+| `/api/v1/statuses` | 10 запросов | 1 минута |
+| `/api/v1/timelines/*` | 60 запросов | 1 минута |
+| `/oauth/token` | 5 запросов | 1 минута |
+| `/api/v1/export` | 1 запрос | 1 час |
+
+---
+
+## Вопросы для обсуждения
+
+- [ ] Нужна ли пагинация через cursor или offset?
+- [ ] Требуется ли версионирование API (`/api/v2/...`)?
+- [ ] Какие поля включать в ответ при ошибке?
+- [ ] Нужна ли поддержка GraphQL для сложных запросов?