Add DOKUMENTASI_API.md
This commit is contained in:
commit
1f4ab74855
|
|
@ -0,0 +1,242 @@
|
|||
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.
|
||||
|
||||
```
|
||||
Loading…
Reference in New Issue