mirror of
https://gitverse.ru/kpa39l/yaru.nixg.ru.git
synced 2026-09-29 18:05:05 +00:00
189 lines
5.3 KiB
Markdown
189 lines
5.3 KiB
Markdown
# 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 для сложных запросов?
|