242 lines
5.9 KiB
Markdown
242 lines
5.9 KiB
Markdown
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`.
|
|
|
|
---
|
|
|
|
```markdown
|
|
# 📡 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:**
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```python
|
|
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.
|
|
|
|
``` |