UniFi API Integration

API Architecture & Integration

The UniFi Dashboard utilizes a Backend-for-Frontend (BFF) architecture. Instead of the browser communicating directly with the UniFi Network API—which would trigger CORS restrictions and expose sensitive credentials—all requests are routed through a local Node.js Express proxy.

Authentication

The integration requires a UniFi API Key and the base URL for your UniFi Controller's integration endpoint. These are configured via environment variables and injected into the proxy's request headers.

| Header | Source | Description | | :--- | :--- | :--- | | X-API-KEY | UNIFI_API_KEY | Your UniFi Network integration key. | | Content-Type | application/json | Default for all requests. |

Proxied Endpoints

The dashboard server exposes a simplified REST API under the /api prefix. These endpoints map directly to the UniFi Network Integration API (v1).

1. Get All Sites

Retrieves a list of all sites managed by the configured UniFi Controller.

• Endpoint: GET /api/sites
• Success Response: 200 OK
• Data Type: Array<Object>
• Usage: Used on initial load to populate the site filter and the main dashboard grid.

2. Get Site Devices

Retrieves the status of all hardware (APIs, Switches, Gateways) for a specific site.

• Endpoint: GET /api/sites/:siteId/devices
• Parameters: siteId (String) - The unique identifier for the UniFi site.
• Success Response: 200 OK
• Data Type: Array<Object>
• Note: The dashboard uses the status field from this response to infer site availability.

3. Get Site Clients

Retrieves all currently active clients connected to the specified site.

• Endpoint: GET /api/sites/:siteId/clients
• Parameters: siteId (String) - The unique identifier for the UniFi site.
• Success Response: 200 OK
• Data Type: Array<Object>
• Usage: Powers the real-time client count and connection notifications.

Data Polling & Refresh Logic

The frontend implementation (app.js) consumes these endpoints using a parallel fetching strategy to ensure the UI remains responsive even with a high number of sites.

// Example of the parallel fetching logic used in the application
const [devices, clients] = await Promise.all([
    fetch(`/api/sites/${siteId}/devices`).then(res => res.json()),
    fetch(`/api/sites/${siteId}/clients`).then(res => res.json())
]);

• Refresh Interval: The dashboard polls the BFF every 15 seconds.
• State Management: Client counts are compared against the previous fetch. If a change is detected, the dashboard triggers visual and (optional) audio notifications.
• Error Handling: If the BFF returns a non-200 status (e.g., the UniFi Controller is unreachable or the API key is invalid), the dashboard displays a persistent error banner and pauses the auto-refresh timer to prevent API rate-limiting.

Error Responses

The proxy translates UniFi API errors into standard JSON responses:

{
  "error": "API request failed: Unauthorized"
}