UniFi Go Library Development

This skill provides expert guidance for developing with **github.com/unpoller/unifi/v5**, a Go library that connects to Ubiquiti UniFi controllers to pull data (clients, devices, sites, alarms, events, etc.). This library is read-only by design.

What This Skill Does

Core Library Patterns

Basic Usage Flow

1. Create `*Config` with controller URL, credentials (user/pass or API key)

2. Call `NewUnifi(config)` to get authenticated `*Unifi` client

3. Fetch `GetSites()` to retrieve site list

4. For each site, call `GetClients(sites)`, `GetDevices(sites)`, etc.

5. Optionally fetch `GetAlarms`, `GetEvents`, `GetAnomalies`, etc.

Data Structures

Go Coding Standards

Linting Requirements

Code Style

Testing

UniFi API Integration

Local Controller API

**Authentication**:

**Endpoint pattern**: `/api/s/{site}/...` where `{site}` is typically `"default"`

**Response format**:

```json

{"data": [...], "meta": {"rc": "ok", "count": 123}}

```

**Error format**:

```json

{"data": [], "meta": {"msg": "api.err.LoginRequired", "rc": "error"}}

```

**Key endpoints** (constants in `types.go`):

**Code patterns**:

Remote Site Manager API (Cloud)

**Base URL**: `https://api.ui.com/v1/`

**Authentication**: API key in `X-API-Key` header (read-only)

**Rate limits**:

**Implementation**: See `remote.go` (`RemoteAPIClient`)

Adding New Features

General Pattern

1. Follow existing patterns in `GetDevices` / `GetClients`

2. Use `GetData(apiPath, &response)` for HTTP requests

3. Add corresponding tests following existing patterns

4. Update mocks to implement full `UnifiClient` interface

5. Run linter and tests before committing

Adding Device/Client Types

1. Extend `Devices` struct with new slice field

2. Update `parseDevices` to handle new type detection

3. Add getter methods following `GetUAPs`/`GetUSWs` style

4. Update `mocks.MockUnifi` to return mock data

5. Add tests for new type parsing and retrieval

Adding API Endpoints

1. Define constant in `types.go` (e.g., `APINewFeaturePath`)

2. Create method on `*Unifi` using `GetData`

3. Define response struct matching API format

4. Add interface method to `UnifiClient`

5. Implement in `mocks.MockUnifi`

6. Add unit tests with mock data

Architecture Notes

Important Constraints

Example Usage

```go

config := &unifi.Config{

URL: "https://unifi.local:8443",

User: "admin",

Pass: "password",

VerifySSL: false,

}

client, err := unifi.NewUnifi(config)

if err != nil {

return fmt.Errorf("failed to create client: %w", err)

}

sites, err := client.GetSites()

if err != nil {

return fmt.Errorf("failed to get sites: %w", err)

}

devices, err := client.GetDevices(sites)

if err != nil {

return fmt.Errorf("failed to get devices: %w", err)

}

// Access typed device slices

for _, uap := range devices.UAPs {

fmt.Printf("AP: %s (%s)\n", uap.Name, uap.MAC)

}

```

Resources