API dan Konfigurasi Runtime

Pendahuluan

Dokumen ini menjelaskan klien API frontend, sistem konfigurasi runtime, grup titik akhir, kontrak respons, dan konvensi parameter kueri.

---

Konfigurasi Runtime

Konfigurasi runtime diimplementasikan di src/config/appConfig.ts.

Prioritas sumber konfigurasi adalah:

1. Konfigurasi Global: globalThis.__APP_CONFIG__
2. Variabel Lingkungan: import.meta.env
3. Default: Fallback yang didefinisikan secara statis di modul hilir

Bentuk Global

interface AppRuntimeConfig {
  VITE_API_BASE_URL?: string;
  VITE_ANALYTICS_AI_CHAT_ENABLED?: string | boolean;
}

Konfigurasi yang Diekspor

interface AppConfig {
  VITE_API_BASE_URL: string;
  VITE_ANALYTICS_AI_CHAT_ENABLED: boolean;
}

appConfig dibekukan (frozen) setelah penguraian untuk mencegah mutasi runtime yang tidak disengaja.

---

Validasi URL

validateUrl() hanya menerima URL http: dan https:. Nilai yang tidak valid akan mengembalikan string kosong dan memicu fallback API.

VITE_API_BASE_URL harus dikonfigurasi tanpa akhiran /api.

Contoh:

VITE_API_BASE_URL=http://localhost:5144
VITE_API_BASE_URL=https://defense-center.example.com

src/lib/api.ts menentukan basis akhir:

export const API_BASE = appConfig.VITE_API_BASE_URL
  ? `${appConfig.VITE_API_BASE_URL}/api`
  : 'http://localhost:5009/api';

---

Penguraian Boolean

VITE_ANALYTICS_AI_CHAT_ENABLED dianggap true hanya untuk nilai berikut:

• true
• 1
• yes
• on

Semua nilai string lainnya, nilai yang hilang, dan nilai yang tidak dikenal akan menghasilkan false.

---

Injeksi Runtime Produksi

docker-entrypoint.sh menulis file ini sebelum memulai Nginx:

window.__APP_CONFIG__ = {
  VITE_API_BASE_URL: "${VITE_API_BASE_URL:-}",
  VITE_ANALYTICS_AI_CHAT_ENABLED: "${VITE_ANALYTICS_AI_CHAT_ENABLED:-false}",
};

Nginx melayani /config.js dengan header no-cache sehingga perubahan konfigurasi runtime segera diterapkan saat penyegaran halaman.

---

Klien Axios

src/lib/api.ts membuat apiClient melalui createApiInstance(API_BASE).

Default Axios:

Pengaturan	Nilai
baseURL	API_BASE
timeout	10000 ms
Content-Type	application/json

Interceptor:

• Permintaan (Request): Membaca token akses dari auth.getToken() dan menambahkan header Authorization.
• Respons: Pada HTTP 401, membersihkan auth dan mengalihkan ke login. Menolak error untuk penanganan khusus pemanggil.

---

Grup Titik Akhir API

Objek api yang diekspor dikelompokkan berdasarkan domain backend:

Grup	Tujuan
auth	Login, daftar, pengguna saat ini, logout
user	CRUD pengguna dan paginasi
organization	CRUD organisasi dan daftar
sensor	CRUD sensor, heartbeat, metrik, token/skrip instalasi, jumlah
virtualSensor	CRUD sensor virtual dan aktivasi/deaktivasi
sensorSetup	Alias lama untuk titik akhir sensor virtual
role	CRUD peran dan paginasi
permission	Katalog izin
location	Pencarian provinsi dan kota
dashboard	Statistik dasbor, log, ringkasan sensor
opensearch	Agregasi analitik keamanan dan daftar peringatan
analyticsChat	Status chat AI dan percakapan yang disimpan
analyticsVirtualSensors	Sensor virtual untuk pemfilteran analitik

---

Konvensi Parameter Kueri

Sebagian besar titik akhir meneruskan parameter objek langsung melalui Axios. Beberapa titik akhir analitik menggunakan buildRepeatedQueryParams() untuk menyerialisasikan array dengan kunci yang berulang:

Contoh: priority=High&priority=Low&protocol=TCP

Digunakan oleh titik akhir seperti:

• /opensearch/dashboard/summary
• /opensearch/alerts/ip-flow
• /opensearch/alerts/list

---

Tipe Respons Bersama

Frontend memodelkan pembungkus backend standar:

Pembungkus Dasar

interface ApiResponse<T> {
  success: boolean;
  data: T;
  errors: string[];
  traceId?: string | null;
}

Payload

interface ListPayload<T> {
  items: T[];
  count: number;
}

interface PaginatedPayload<T> {
  items: T[];
  pagination: {
    currentPage: number;
    pageSize: number;
    totalCount: number;
    totalPages: number;
  };
}

---

API Streaming

Streaming chat AI analitik menggunakan fetch dan chunk bergaya Server-Sent Events.

Titik Akhir: POST /api/analytics/chat/conversations/:conversationId/stream

Event yang Ditangani:

• start (onStart)
• chunk (onChunk)
• complete (onComplete)
• error (onError)

Pengurai stream membaca baris event: dan data:, mengurai payload JSON, dan menangani pembersihan di blok finally.