Add API.md
This commit is contained in:
parent
1f4ab74855
commit
d1470f660c
|
|
@ -0,0 +1,237 @@
|
|||
Berikut adalah **Dokumentasi API Lengkap** untuk VSOL Multi-OLT API v3.0 (versi Database).
|
||||
Dokumentasi ini mencakup cara konfigurasi (CRUD OLT) dan cara monitoring.
|
||||
|
||||
Anda bisa menyimpannya sebagai `API_DOCS.md` atau `README.md`.
|
||||
|
||||
---
|
||||
|
||||
# 📡 VSOL Multi-OLT API v3.0 (Database Support)
|
||||
|
||||
Service REST API ini berfungsi sebagai middleware untuk memonitor dan mengelola banyak OLT VSOL sekaligus. Konfigurasi OLT disimpan secara persisten menggunakan database SQLite.
|
||||
|
||||
## 📋 Informasi Dasar
|
||||
|
||||
* **Base URL:** `http://<IP_SERVER>:8000`
|
||||
* **Content-Type:** `application/json`
|
||||
* **Swagger UI (Interactive):** `http://<IP_SERVER>:8000/docs`
|
||||
* **Database:** `vsol.db` (SQLite, otomatis dibuat saat dijalankan)
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 1. Manajemen Konfigurasi OLT (CRUD)
|
||||
|
||||
Bagian ini digunakan untuk mendaftarkan, melihat, dan menghapus OLT dari sistem monitoring. Perubahan di sini bersifat **Hot-Reload** (langsung aktif tanpa restart script).
|
||||
|
||||
### A. Lihat Daftar OLT
|
||||
|
||||
Mendapatkan semua OLT yang sudah terdaftar di database.
|
||||
|
||||
* **Endpoint:** `GET /system/olts`
|
||||
* **Response (200 OK):**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "OLT Pusat (Kediri)",
|
||||
"ip": "http://192.168.100.1:80",
|
||||
"user": "admin"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"name": "OLT Cabang Selatan",
|
||||
"ip": "http://10.10.10.1:8888",
|
||||
"user": "operator"
|
||||
}
|
||||
]
|
||||
|
||||
```
|
||||
|
||||
### B. Tambah OLT Baru
|
||||
|
||||
Mendaftarkan OLT baru ke dalam sistem.
|
||||
|
||||
* **Endpoint:** `POST /system/olts`
|
||||
* **Body (JSON):**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "OLT Baru",
|
||||
"ip": "http://ip.wuznet.com:88", // Masukkan URL login (http://IP:PORT)
|
||||
"user": "andri",
|
||||
"password": "Notif123!x"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
* **Response (200 OK):**
|
||||
|
||||
```json
|
||||
{
|
||||
"msg": "OLT Added successfully",
|
||||
"id": 3
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### C. Hapus OLT
|
||||
|
||||
Menghapus OLT dari sistem monitoring berdasarkan ID-nya.
|
||||
|
||||
* **Endpoint:** `DELETE /system/olts/{olt_id}`
|
||||
* **Parameter Path:** `olt_id` (Integer)
|
||||
* **Response (200 OK):**
|
||||
|
||||
```json
|
||||
{
|
||||
"msg": "OLT 2 deleted"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 2. Monitoring & Dashboard
|
||||
|
||||
Bagian ini digunakan oleh frontend/dashboard untuk menampilkan data real-time dari OLT.
|
||||
|
||||
### A. Dashboard Statistik (Home)
|
||||
|
||||
Mengambil ringkasan kesehatan OLT (Total ONU, Status Online/Offline, dan Kesehatan Sinyal).
|
||||
|
||||
* **Endpoint:** `GET /dashboard/stats`
|
||||
* **Query Parameter:** `olt_id` (Wajib)
|
||||
* **Contoh Request:** `GET /dashboard/stats?olt_id=1`
|
||||
* **Response (200 OK):**
|
||||
|
||||
```json
|
||||
{
|
||||
"olt_name": "OLT Pusat",
|
||||
"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 (Perlu perbaikan)
|
||||
"avg_rx": -19.45 // Rata-rata redaman
|
||||
},
|
||||
"last_update": "13:45:00"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### B. Daftar Semua ONU (List)
|
||||
|
||||
Mengambil tabel lengkap semua ONU beserta status ringkasnya.
|
||||
|
||||
* **Endpoint:** `GET /onu/list`
|
||||
* **Query Parameter:** `olt_id` (Wajib)
|
||||
* **Response (200 OK):**
|
||||
|
||||
```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 UI (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"
|
||||
}
|
||||
]
|
||||
|
||||
```
|
||||
|
||||
### C. Detail Lengkap ONU ("Kartu Pasien")
|
||||
|
||||
Mengambil data mendalam untuk satu ONU tertentu (menggabungkan info status, optik, diagnosa, dan hardware).
|
||||
|
||||
* **Endpoint:** `GET /onu/detail`
|
||||
* **Query Parameters:**
|
||||
* `olt_id`: ID OLT (Contoh: `1`)
|
||||
* `id`: ID ONU (Contoh: `EPON0/1:1`)
|
||||
|
||||
|
||||
* **Contoh Request:** `GET /onu/detail?olt_id=1&id=EPON0/1:1`
|
||||
* **Response (200 OK):**
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tips Integrasi
|
||||
|
||||
1. **Polling Interval:** Disarankan me-refresh data (`/dashboard/stats` atau `/onu/list`) setiap **10-15 detik**. Jangan terlalu cepat agar CPU OLT tidak terbebani. API ini sendiri memiliki fitur *cache* selama 20 detik.
|
||||
2. **Error Handling:** Jika OLT mati atau credential salah, API akan mengembalikan HTTP Error 404 atau 500. Pastikan aplikasi frontend Anda menangani error ini dengan baik (misalnya menampilkan pesan "Connection Lost").
|
||||
3. **URL Encoding:** Saat memanggil `/onu/detail`, pastikan parameter `id` di-encode jika menggunakan curl/library tertentu, meskipun browser modern biasanya menanganinya otomatis.
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ Contoh Penggunaan (cURL)
|
||||
|
||||
**1. Menambah OLT Baru:**
|
||||
|
||||
```bash
|
||||
curl -X 'POST' \
|
||||
'http://localhost:8000/system/olts' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"name": "OLT Wuznet",
|
||||
"ip": "http://ip.wuznet.com:88",
|
||||
"user": "andri",
|
||||
"password": "YOUR_PASSWORD"
|
||||
}'
|
||||
|
||||
```
|
||||
|
||||
**2. Melihat Data ONU:**
|
||||
|
||||
```bash
|
||||
curl 'http://localhost:8000/onu/list?olt_id=1'
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
Loading…
Reference in New Issue