api_olt_vsol/DOKUMENTASI_API.md

Berikut adalah Dokumentasi API Lengkap (VSOL Multi-OLT Manager v2.1).

Dokumentasi ini dirancang agar mudah dibaca oleh frontend developer atau untuk keperluan integrasi dengan sistem lain (seperti Grafana, Telegram Bot, atau Web Dashboard Custom).

Silakan simpan ini sebagai file README.md atau API_DOCS.md.

---

# 📡 VSOL Multi-OLT API Documentation v2.1

Service ini berfungsi sebagai **Middleware (Jembatan)** yang mengubah antarmuka web HTML OLT VSOL (yang jadul) menjadi **RESTful JSON API** modern. Mendukung multiple OLT management dalam satu endpoint.

## 📋 Base Information

* **Base URL:** `http://<IP_SERVER>:8000`
* **Content-Type:** `application/json`
* **Interactive Docs (Swagger UI):** `http://<IP_SERVER>:8000/docs` (Sangat direkomendasikan untuk testing langsung).
* **Redoc:** `http://<IP_SERVER>:8000/redoc`

---

## 🚀 Daftar Endpoints

### 1. Cek Kesehatan Sistem (Health Check)
Memastikan service API berjalan normal.

* **Endpoint:** `GET /`
* **Parameters:** Tidak ada.

**Response:**
```json
{
  "msg": "VSOL Multi-OLT API Ready"
}

---

2. Mendapatkan Daftar OLT

Mendapatkan list server OLT yang terdaftar di konfigurasi OLT_LIST.

• Endpoint: GET /system/olts
• Parameters: Tidak ada.

Response:

[
  {
    "id": 1,
    "name": "OLT Wuznet (Main)",
    "ip": "[http://ip.wuznet.com:88](http://ip.wuznet.com:88)"
  },
  {
    "id": 2,
    "name": "OLT Cabang Selatan",
    "ip": "[http://192.168.1.100](http://192.168.1.100)"
  }
]

---

3. Dashboard Statistik

Mengambil ringkasan data untuk ditampilkan di halaman depan (Home) dashboard. Data mencakup jumlah total, online, offline, dan kesehatan sinyal.

• Endpoint: GET /dashboard/stats
• Parameters:

Parameter	Tipe	Wajib	Deskripsi
olt_id	int	Ya	ID dari OLT (didapat dari endpoint /system/olts)

Contoh Request: GET /dashboard/stats?olt_id=1

Response:

{
  "olt_name": "OLT Wuznet (Main)",
  "total_onu": 61,
  "online": 57,
  "offline": 4,
  "signal_health": {
    "good": 50,      // Sinyal > -24 dBm
    "warning": 5,    // Sinyal antara -24 s/d -27 dBm
    "critical": 2,   // Sinyal < -27 dBm
    "avg_rx": -19.45 // Rata-rata sinyal
  },
  "last_update": "10:30:15"
}

---

4. Mendapatkan List Semua ONU

Mengambil daftar tabel semua ONU beserta status ringkas (Status, Sinyal, Jarak).

• Endpoint: GET /onu/list
• Parameters:

Parameter	Tipe	Wajib	Deskripsi
olt_id	int	Ya	ID dari OLT.

Contoh Request: GET /onu/list?olt_id=1

Response:

[
  {
    "id": "EPON0/1:1",
    "mac": "D4:D5:1B:63:6B:00",
    "name": "Yuli_Setianingati",
    "status": "Online",
    "rx_power": "-18.04",
    "tx_power": "2.21",
    "distance": "1147",
    "status_color": "green" // Helper untuk frontend (green/red)
  },
  {
    "id": "EPON0/1:2",
    "mac": "A4:BE:2B:4C:BF:15",
    "name": "Pelanggan_B",
    "status": "Offline",
    "rx_power": "N/A",
    "tx_power": "N/A",
    "distance": "-",
    "status_color": "red"
  }
]

---

5. Detail Lengkap ONU

Mengambil data detail ("Kartu Pasien") dari satu ONU tertentu. Menggabungkan data Status, Optik, Info Dasar, dan Diagnosa.

• Endpoint: GET /onu/detail
• Parameters:

Parameter	Tipe	Wajib	Deskripsi
olt_id	int	Ya	ID dari OLT.
id	str	Ya	ID ONU (Contoh: EPON0/1:1). Case insensitive.

Contoh Request: GET /onu/detail?olt_id=1&id=EPON0/1:1

Response:

{
  "id": "EPON0/1:1",
  "basic_info": {
    "name": "Yuli_Setianingati",
    "mac": "D4:D5:1B:63:6B:00",
    "model": "V4.2",
    "vendor": "ZTE",
    "soft_ver": "V1.0.2"
  },
  "optical_info": {
    "rx_power": "-18.04",
    "tx_power": "2.21",
    "distance": "1147",
    "voltage": "3.25",
    "temperature": "45.2"
  },
  "status_info": {
    "status": "Online",
    "last_online": "2026/02/12 10:00:00",
    "last_offline": "2026/02/10 05:00:00",
    "uptime": "2 Days 5 Hours"
  },
  "diagnose_info": {
    "offline_reason": "Power Off" // Alasan mati terakhir
  }
}

---

🛠️ Cara Penggunaan (Contoh Python)

Berikut adalah contoh snippet Python sederhana untuk mengambil data dari API ini:

import requests

API_URL = "http://localhost:8000"

# 1. Ambil List OLT
olts = requests.get(f"{API_URL}/system/olts").json()
print("OLT Tersedia:", olts)

# 2. Ambil Statistik OLT Pertama (ID=1)
stats = requests.get(f"{API_URL}/dashboard/stats", params={"olt_id": 1}).json()
print(f"Total ONU: {stats['total_onu']}")
print(f"Sinyal Rata-rata: {stats['signal_health']['avg_rx']} dBm")

# 3. Cari Detail ONU
onu_id = "EPON0/1:1"
detail = requests.get(f"{API_URL}/onu/detail", params={"olt_id": 1, "id": onu_id}).json()
print(f"Status {onu_id}: {detail['status_info']['status']}")
print(f"Rx Power: {detail['optical_info']['rx_power']} dBm")

⚠️ Catatan Penting

1. Caching: Data di-cache selama 20 detik di sisi server. Jika Anda melakukan request berulang kali dalam waktu < 20 detik, Anda akan mendapatkan data yang sama. Ini fitur keamanan agar CPU OLT tidak overload.
2. SessionKey: API otomatis menangani login dan pengambilan SessionKey. Jika sesi OLT habis, API akan otomatis melakukan login ulang di background (mungkin butuh waktu 1-2 detik lebih lama saat request pertama setelah expired).
3. URL Encoding: Jika menggunakan browser/curl manual, karakter / pada ID ONU sebaiknya di-encode menjadi %2F (meskipun API ini sudah mendukung query param standar).

• Benar: ?id=EPON0/1:1 atau ?id=EPON0%2F1%3A1

### Tips Tambahan:

Karena Anda menggunakan **FastAPI**, dokumentasi di atas sebenarnya sudah tersedia secara **Otomatis & Interaktif** di browser Anda.

Cukup buka browser dan ketik:
> **`http://<IP_SERVER_ANDA>:8000/docs`**

Di sana Anda bisa langsung mencoba tombol **"Try it out"**, mengisi kolom `olt_id`, dan melihat langsung respon JSON-nya tanpa perlu coding.