mirror of https://github.com/ospab/ostp.git
150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
# Справочник 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-конфиг.
|