OpenVPN-Monitoring-Simple/DOCS/api_v3_endpoints.md

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	Принудительная детализация данных. Значения: auto — автоматический выбор (см. логику ниже) raw — сырые данные (каждые 10-30 сек) 5min — 5 минут hourly — 1 час 6h — 6 часов daily — 1 день

Логика resolution=auto

API автоматически выбирает таблицу источника данных в зависимости от длительности диапазона:

• ≤ 24 часов: usage_history (Сырые данные)
• ≤ 7 дней: stats_hourly (Агрегация по часам)
• ≤ 3 месяцев: stats_6h (Агрегация по 6 часов)
• > 3 месяцев: stats_daily (Агрегация по дням)

Пример запроса

GET /api/v1/stats/user-alice?range=7d

Пример ответа

{
  "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

Пример ответа

{
  "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

Пример ответа

{
  "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

Пример ответа

{
  "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

{
  "success": true,
  "data": [
    {"common_name": "user-alice", "status": "Active"},
    {"common_name": "user-bob", "status": "Disconnected"}
  ]
}

Проверка здоровья (Health Check)

Проверяет доступность базы данных.

GET /health

{
  "success": true,
  "status": "healthy"
}