init commit
This commit is contained in:
Антон
202
DOCS/api_v3_endpoints.md
Normal file
202
DOCS/api_v3_endpoints.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# OpenVPN Monitor API v2 Documentation
|
||||
|
||||
Этот API предоставляет доступ к данным мониторинга OpenVPN, включая статус клиентов в реальном времени и исторические данные, хранящиеся в Time Series Database (TSDB).
|
||||
|
||||
**Base URL:** `http://<your-server-ip>:5001/api/v1`
|
||||
|
||||
---
|
||||
|
||||
## 1. Статистика по клиенту (Детальная + История)
|
||||
|
||||
Основной эндпоинт для построения графиков и отчетов. Поддерживает динамическую агрегацию данных (умный выбор детализации).
|
||||
|
||||
### `GET /stats/<common_name>`
|
||||
|
||||
#### Параметры запроса (Query Parameters)
|
||||
|
||||
| Параметр | Тип | По умолчанию | Описание |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `range` | string | `24h` | Период выборки. Поддерживаются форматы: `24h` (часы), `7d` (дни), `30d`, `1y` (годы). |
|
||||
| `resolution` | string | `auto` | Принудительная детализация данных. <br>**Значения:**<br>`auto` — автоматический выбор (см. логику ниже)<br>`raw` — сырые данные (каждые 10-30 сек)<br>`5min` — 5 минут<br>`hourly` — 1 час<br>`6h` — 6 часов<br>`daily` — 1 день |
|
||||
|
||||
#### Логика `resolution=auto`
|
||||
API автоматически выбирает таблицу источника данных в зависимости от длительности диапазона:
|
||||
* **≤ 24 часов:** `usage_history` (Сырые данные)
|
||||
* **≤ 7 дней:** `stats_hourly` (Агрегация по часам)
|
||||
* **≤ 3 месяцев:** `stats_6h` (Агрегация по 6 часов)
|
||||
* **> 3 месяцев:** `stats_daily` (Агрегация по дням)
|
||||
|
||||
#### Пример запроса
|
||||
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d
|
||||
|
||||
```
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"timestamp": "2026-01-08 14:30:00",
|
||||
"data": {
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"real_address": "192.168.1.50:54321",
|
||||
"last_activity": "N/A",
|
||||
"current_rates": {
|
||||
"recv_mbps": 1.5,
|
||||
"sent_mbps": 0.2
|
||||
},
|
||||
"totals": {
|
||||
"received_mb": 500.25,
|
||||
"sent_mb": 120.10
|
||||
},
|
||||
"meta": {
|
||||
"resolution_used": "stats_hourly",
|
||||
"start": "2026-01-01 14:30:00",
|
||||
"end": "2026-01-08 14:30:00",
|
||||
"record_count": 168
|
||||
},
|
||||
"history": [
|
||||
{
|
||||
"timestamp": "2026-01-01 15:00:00",
|
||||
"bytes_received": 1048576,
|
||||
"bytes_sent": 524288,
|
||||
"bytes_received_rate_mbps": 0,
|
||||
"bytes_sent_rate_mbps": 0
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> **Примечание:** Поля `*_rate_mbps` в массиве `history` возвращают `0` для агрегированных данных (hourly, daily), так как агрегация хранит только суммарный объем трафика.
|
||||
|
||||
---
|
||||
|
||||
## 2. Текущая статистика (Все клиенты)
|
||||
|
||||
Возвращает мгновенный снимок состояния всех известных клиентов.
|
||||
|
||||
### `GET /stats`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"count": 2,
|
||||
"data": [
|
||||
{
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"real_address": "192.168.1.50:54321",
|
||||
"current_recv_rate_mbps": 1.5,
|
||||
"current_sent_rate_mbps": 0.2,
|
||||
"total_received_mb": 500.25,
|
||||
"total_sent_mb": 120.10,
|
||||
"last_activity": "N/A"
|
||||
},
|
||||
{
|
||||
"common_name": "user-bob",
|
||||
"status": "Disconnected",
|
||||
"real_address": null,
|
||||
"current_recv_rate_mbps": 0,
|
||||
"current_sent_rate_mbps": 0,
|
||||
"total_received_mb": 1500.00,
|
||||
"total_sent_mb": 300.00,
|
||||
"last_activity": "2026-01-08 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Системная статистика
|
||||
|
||||
Сводная информация по всему серверу OpenVPN.
|
||||
|
||||
### `GET /stats/system`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"total_clients": 15,
|
||||
"active_clients": 3,
|
||||
"total_bytes_received": 10737418240,
|
||||
"total_bytes_sent": 5368709120,
|
||||
"total_received_gb": 10.0,
|
||||
"total_sent_gb": 5.0
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Сертификаты
|
||||
|
||||
Информация о сроках действия SSL сертификатов пользователей.
|
||||
|
||||
### `GET /certificates`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"file": "user-alice.crt",
|
||||
"common_name": "user-alice",
|
||||
"days_remaining": "360 days",
|
||||
"is_expired": false,
|
||||
"not_after": "Jan 8 12:00:00 2027 GMT"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Вспомогательные методы
|
||||
|
||||
### Список клиентов (Упрощенный)
|
||||
|
||||
Используется для заполнения выпадающих списков в интерфейсе.
|
||||
|
||||
### `GET /clients`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{"common_name": "user-alice", "status": "Active"},
|
||||
{"common_name": "user-bob", "status": "Disconnected"}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Проверка здоровья (Health Check)
|
||||
|
||||
Проверяет доступность базы данных.
|
||||
|
||||
### `GET /health`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"status": "healthy"
|
||||
}
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user