e79dcb13f0
* feat: add support for logging * fix linting * chore: remove old APIError in favor of ServerError
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
// 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](../unifi/client.generated.go).
|
|
|
|
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`:
|
|
```go
|
|
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](./getting_started.md#BareClientInitialization)
|
|
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](./configuration.md).
|