From 1f4ab74855f4e3ec00c40ff984d70bef99d08b31 Mon Sep 17 00:00:00 2001 From: andri Date: Thu, 12 Feb 2026 18:05:06 +0000 Subject: [PATCH] Add DOKUMENTASI_API.md --- DOKUMENTASI_API.md | 242 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 DOKUMENTASI_API.md diff --git a/DOKUMENTASI_API.md b/DOKUMENTASI_API.md new file mode 100644 index 0000000..8d1789a --- /dev/null +++ b/DOKUMENTASI_API.md @@ -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://:8000` +* **Content-Type:** `application/json` +* **Interactive Docs (Swagger UI):** `http://:8000/docs` (Sangat direkomendasikan untuk testing langsung). +* **Redoc:** `http://: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://: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. + +``` \ No newline at end of file