Struct UnifiClient 

pub struct UnifiClient { /* private fields */ }

Implementations

impl UnifiClient

pub fn new(base_url: impl Into<String>) -> Result<Self>

Create a new client for UniFi controller access with strict TLS validation.

This constructor requires valid TLS certificates. If your controller uses a self-signed certificate, use new_insecure instead.

Example

use rustifi::UnifiClient;

let client = UnifiClient::new("https://unifi.example.com")?;

pub fn new_insecure(base_url: impl Into<String>) -> Result<Self>

Create a new client that accepts invalid/self-signed TLS certificates.

Security Warning

This disables TLS certificate validation. Only use this for local controllers with self-signed certificates on trusted networks. Using this over untrusted networks exposes you to man-in-the-middle attacks.

For production environments or controllers with valid certificates, use new instead.

Example

use rustifi::UnifiClient;

// Only for local controllers with self-signed certs
let client = UnifiClient::new_insecure("https://192.168.1.1")?;

pub fn with_base_path( base_url: impl Into<String>, base_path: impl Into<String>, ) -> Result<Self>

Create a new client with a custom base path and strict TLS validation.

Arguments

• base_url - The base URL of the UniFi controller
• base_path - The API base path (e.g., “/api/v1”)

Example

use rustifi::UnifiClient;

let client = UnifiClient::with_base_path("https://unifi.example.com", "/api/v2")?;

pub fn with_base_path_insecure( base_url: impl Into<String>, base_path: impl Into<String>, ) -> Result<Self>

Create a new client with a custom base path that accepts invalid TLS certificates.

Security Warning

This disables TLS certificate validation. Only use this for local controllers with self-signed certificates on trusted networks. Using this over untrusted networks exposes you to man-in-the-middle attacks.

Arguments

• base_url - The base URL of the UniFi controller
• base_path - The API base path (e.g., “/api/v1”)

Example

use rustifi::UnifiClient;

// Only for local controllers with self-signed certs
let client = UnifiClient::with_base_path_insecure("https://192.168.1.1", "/api/v1")?;

pub fn with_api_key( base_url: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Create a client with an API key and strict TLS validation.

Errors

Returns an error if the API key contains invalid HTTP header characters.

Example

use rustifi::UnifiClient;

let client = UnifiClient::with_api_key("https://unifi.example.com", "your-api-key")?;

pub fn with_api_key_insecure( base_url: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Create a client with an API key that accepts invalid TLS certificates.

Security Warning

This disables TLS certificate validation. Only use this for local controllers with self-signed certificates on trusted networks.

Errors

Returns an error if the API key contains invalid HTTP header characters.

Example

use rustifi::UnifiClient;

// Only for local controllers with self-signed certs
let client = UnifiClient::with_api_key_insecure("https://192.168.1.1", "your-api-key")?;

pub fn with_base_path_and_key( base_url: impl Into<String>, base_path: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Create a client with a custom base path and API key (strict TLS).

Errors

Returns an error if the API key contains invalid HTTP header characters.

Example

use rustifi::UnifiClient;

let client = UnifiClient::with_base_path_and_key(
    "https://unifi.example.com",
    "/api/v1",
    "your-api-key"
)?;

pub fn with_base_path_and_key_insecure( base_url: impl Into<String>, base_path: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Create a client with a custom base path and API key that accepts invalid TLS certificates.

Security Warning

This disables TLS certificate validation. Only use this for local controllers with self-signed certificates on trusted networks.

Errors

Returns an error if the API key contains invalid HTTP header characters.

Example

use rustifi::UnifiClient;

// Only for local controllers with self-signed certs
let client = UnifiClient::with_base_path_and_key_insecure(
    "https://192.168.1.1",
    "/api/v1",
    "your-api-key"
)?;

pub fn remote( api_key: impl Into<String>, host_id: impl Into<String>, ) -> Result<Self>

Create a client for remote API access via api.ui.com.

This allows accessing UniFi consoles remotely through Ubiquiti’s cloud. Requires firmware version >= 5.0.3 on the target console.

Arguments

• api_key - Your UI.com API key (site-manager-api-key)
• host_id - The Host ID of the console to connect to (format: 900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789)

Errors

Returns an error if the API key contains invalid HTTP header characters.

Example

use rustifi::UnifiClient;

let client = UnifiClient::remote("your-api-key", "your-host-id")?;

pub fn api_key(&self) -> Option<&str>

pub fn host_id(&self) -> Option<&str>

Returns the host ID if this is a remote API client.

pub fn is_remote(&self) -> bool

Returns true if this client is configured for remote API access.

pub async fn execute<E>(&self, endpoint: &E) -> Result<E::Response>

where E: Endpoint, E::Response: for<'a> Deserialize<'a>,

Execute a request for an endpoint instance. Use this when the endpoint has dynamic path parameters.

pub async fn request<E>(&self) -> Result<E::Response>

where E: Endpoint + Default, E::Response: for<'a> Deserialize<'a>,

Execute a request for endpoints without dynamic path parameters. For endpoints with path parameters, use execute() instead.

pub fn base_url(&self) -> &str

pub fn base_path(&self) -> &str

impl UnifiClient

Extension methods for UnifiClient to support pagination.

pub async fn fetch_all_clients(&self, site_id: &str) -> Result<Vec<Client>>

Fetch all clients for a site, automatically handling pagination.

This method fetches all pages sequentially and returns a complete list. For large datasets, consider using stream_clients() instead.

Example

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;
let all_clients = client.fetch_all_clients("site-id").await?;
println!("Total clients: {}", all_clients.len());

pub async fn fetch_all_devices(&self, site_id: &str) -> Result<Vec<SiteDevice>>

Fetch all devices for a site, automatically handling pagination.

This method fetches all pages sequentially and returns a complete list. For large datasets, consider using stream_devices() instead.

Example

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;
let all_devices = client.fetch_all_devices("site-id").await?;
println!("Total devices: {}", all_devices.len());

pub fn stream_clients(&self, site_id: &str) -> PageStream<'_, Client>

Create a stream that yields pages of clients.

This is useful for processing clients in batches without loading everything into memory at once.

Example

use futures::StreamExt;

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;
let mut stream = client.stream_clients("site-id");

while let Some(result) = stream.next().await {
    let page = result?;
    for client in page {
        println!("Client: {}", client.id);
    }
}

pub fn stream_devices(&self, site_id: &str) -> PageStream<'_, SiteDevice>

Create a stream that yields pages of devices.

This is useful for processing devices in batches without loading everything into memory at once.

Example

use futures::StreamExt;

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;
let mut stream = client.stream_devices("site-id");

while let Some(result) = stream.next().await {
    let page = result?;
    for device in page {
        println!("Device: {} ({})", device.name, device.id);
    }
}

impl UnifiClient

Extension methods for UnifiClient to fetch combined device information.

pub async fn fetch_device_with_info( &self, site_id: &str, device_id: &str, ) -> Result<DeviceWithInfo>

Fetch a device with its details and statistics in parallel.

This method makes three API calls in parallel:

• Get the device basic info
• Get the device details (ports, radios, features)
• Get the device statistics (CPU, memory, uplink rates)

Arguments

• site_id - The site ID
• device_id - The device ID

Example

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;

let device = client.fetch_device_with_info("site-id", "device-id").await?;

println!("Device: {}", device.name());
println!("Uptime: {}", device.uptime_formatted());
println!("CPU: {:?}%", device.cpu_utilization());

pub async fn fetch_all_devices_with_info( &self, site_id: &str, ) -> Result<Vec<DeviceWithInfo>>

Fetch all devices with their details and statistics.

This method first fetches all devices, then fetches details and statistics for each device in parallel. This is more efficient than making sequential calls for each device.

Note: The returned order may differ from the original device list order due to parallel request processing.

Arguments

• site_id - The site ID

Example

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;

let devices = client.fetch_all_devices_with_info("site-id").await?;

for device in devices {
    println!("{}: {} ({})",
        device.name(),
        if device.is_online() { "online" } else { "offline" },
        device.uptime_formatted()
    );
}

pub async fn fetch_client_stats_by_device( &self, site_id: &str, ) -> Result<HashMap<String, DeviceClientStats>>

Fetch all clients and aggregate statistics by device.

This fetches all clients (handling pagination) and returns a HashMap of device_id -> DeviceClientStats.

Arguments

• site_id - The site ID

Example

let client = UnifiClient::with_api_key("https://unifi.example.com", "api-key")?;

let stats = client.fetch_client_stats_by_device("site-id").await?;

for (device_id, device_stats) in &stats {
    println!("Device {}: {} clients ({} guests)",
        device_id,
        device_stats.total_clients,
        device_stats.guest_clients
    );
}

Trait Implementations

impl Clone for UnifiClient

fn clone(&self) -> UnifiClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnifiClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.