# 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 для сложных запросов?