# Справочник API управления OSTP

Сервер OSTP предоставляет REST API для управления пользователями, просмотра статистики трафика и интерактивного редактирования конфигурации.

По умолчанию API слушает на порту `9090` (хост настраивается в файле конфигурации).

---

## Авторизация

Все запросы к API (за исключением подписок) должны содержать заголовок `Authorization` с API-токеном (если токен включен в конфигурационном файле):

```http
Authorization: Bearer <ваш_api_токен>
```

Или в упрощенном виде:
```http
Authorization: <ваш_api_токен>
```

---

## Формат ответов

Все ответы API возвращаются в формате JSON следующей структуры:

```json
{
  "ok": true,
  "data": ...,
  "error": null
}
```

В случае ошибки:
```json
{
  "ok": false,
  "data": null,
  "error": "Описание ошибки"
}
```

---

## Список эндпоинтов

### 1. Статус сервера
Возвращает текущую версию, аптайм и количество пользователей.

* **URL**: `/api/server/status`
* **Метод**: `GET`
* **Формат `data`**:
  ```json
  {
    "version": "0.2.30",
    "uptime_seconds": 12053,
    "active_users": 2,
    "total_users": 5
  }
  ```

### 2. Получение текущего конфига
Запрашивает полное содержимое файла `config.json` с удалением комментариев для прямой модификации.

* **URL**: `/api/server/config`
* **Метод**: `GET`
* **Формат `data`**: Полный JSON-конфиг сервера.

### 3. Обновление конфига
Записывает новый JSON конфигурации сервера в файл `config.json` на диске. Это автоматически вызывает **hot-reload** ядра (применение ключей доступа и лимитов).

* **URL**: `/api/server/config`
* **Метод**: `PUT`
* **Тело запроса**: JSON нового конфигурационного файла.
* **Формат `data`**: `true` в случае успешного сохранения.

### 4. Список клиентов и их статистики
Возвращает список всех зарегистрированных ключей доступа с их текущей загрузкой, скачиванием, активными сессиями и статусом подключения.

* **URL**: `/api/users`
* **Метод**: `GET`
* **Формат `data`**:
  ```json
  [
    {
      "access_key": "ostp_key_sample1",
      "bytes_up": 2405020,
      "bytes_down": 491029402,
      "connections": 2,
      "limit_bytes": 10737418240,
      "online": true,
      "name": "Ноутбук"
    }
  ]
  ```

### 5. Создание клиента
Генерирует новый ключ доступа (или регистрирует пользовательский).

* **URL**: `/api/users`
* **Метод**: `POST`
* **Тело запроса**:
  ```json
  {
    "access_key": "my_custom_key_optional",
    "name": "Имя клиента",
    "limit_bytes": 50000000000
  }
  ```
* **Формат `data`**: Строка созданного ключа доступа.

### 6. Удаление клиента
Отзывает ключ доступа и сбрасывает все связанные активные сессии.

* **URL**: `/api/users/:key`
* **Метод**: `DELETE`
* **Формат `data`**: `"User removed"`

### 7. Обновление клиента
Редактирует имя или лимит трафика для клиента.

* **URL**: `/api/users/:key`
* **Метод**: `PUT`
* **Тело запроса**:
  ```json
  {
    "name": "Новое имя",
    "limit_bytes": 100000000000
  }
  ```
* **Формат `data`**: `"User updated"`

### 8. Сброс счетчиков трафика
Обнуляет показания загрузки и скачивания для определенного пользователя.

* **URL**: `/api/users/{key}/reset`
* **Метод**: `POST`
* **Формат `data`**: `true`

### 9. Ссылка подписки клиента
Возвращает ссылку подписки или конфигурационный файл для клиента. Авторизация по Bearer-токену **не требуется** (ключ авторизуется сам через URL).

* **URL**: `/api/subscribe/:key`
* **Метод**: `GET`
* **Заголовки**:
  - `Accept: text/plain` -> Возвращает текстовую ссылку `ostp://<key>@<host>:<port>?...`
  - `Accept: application/json` -> Возвращает полный клиентский JSON-конфиг.