go-unifi/docs/migrating_from_upstream.md

Migrating from paultyng/go-unifi

This guide will help you migrate from paultyng/go-unifi to filipowm/go-unifi. The main differences are in how the client is initialized, while all client methods remain the same, with additional methods covering of the UniFi Controller API.

Client Initialization Changes

paultyng/go-unifi Style

In the upstream library, client initialization typically looks like this:

client := unifi.Client{}
client.SetBaseURL("https://unifi.localdomain")

// Optional: Configure TLS
if skipTLSVerify {
    httpClient := &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
        },
    }
    jar, _ := cookiejar.New(nil)
    httpClient.Jar = jar
    client.SetHTTPClient(httpClient)
}

// Login is required
err := client.Login(ctx, username, password)
if err != nil {
    return nil, err
}

filipowm/go-unifi Style

The new library provides a more structured and configurable approach:

// Using API Key (recommended, requires UniFi Controller 9.0.108+)
client, err := unifi.NewClient(&unifi.ClientConfig{
    BaseURL: "https://unifi.localdomain",
    APIKey:  "your-api-key",
})

// OR using username/password
client, err := unifi.NewClient(&unifi.ClientConfig{
    BaseURL:  "https://unifi.localdomain",
    Username: "your-username",
    Password: "your-password",
})

if err != nil {
    log.Fatalf("Failed to create client: %v", err)
}

Key Differences

1. Client Creation:

   • Old: Manual client creation and configuration using setters. Client used is a struct.
   • New: Builder pattern with NewClient function and ClientConfig struct. Client used is an interface.

2. Authentication:

   • Old: Only username/password authentication with explicit Login() call
   • New: Supports both API Key (recommended) and username/password authentication
   • New: Login is handled automatically during client creation

3. HTTP Client Configuration:

   • Old: Manual HTTP client configuration with SetHTTPClient and manual creation of http.Client and cookiejar.Jar
   • New: Built-in configuration options through ClientConfig:
     • HttpTransportCustomizer for transport-level customization
     • HttpRoundTripperProvider for complete HTTP client control

4. Removed unifi.APIError:

   • Old: unifi.APIError struct for API errors
   • New: Standard unifi.ServerError struct for API errors

5. Additional Features in filipowm/go-unifi:

   • Validation modes (Soft, Hard, Disabled)
   • Request/Response interceptors
   • Custom error handling
   • Comprehensive configuration options

Migration Steps

1. Replace the import from github.com/paultyng/go-unifi to github.com/filipowm/go-unifi
2. Replace manual client creation with NewClient and appropriate ClientConfig
3. If using TLS skip verification, use the VerifySSL option in ClientConfig:

   client, err := unifi.NewClient(&unifi.ClientConfig{
       BaseURL: "https://unifi.localdomain",
       APIKey:  "your-api-key",
       VerifySSL: false,
   })
   

4. Remove explicit Login() calls as they are now handled automatically, unless you use bare client initialization
5. Replace usage of unifi.APIError with unifi.ServerError

The rest of your code using the client methods should continue to work as before, as the API methods remain the same.

For details on configuring client, check client configuration.