# 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"
}

```