Configuration types
Every ClientConfig field with its type and default, plus the ValidationMode, APIStyle, and logging enums.
ClientConfig is the single struct you pass to NewClient. Only URL and
APIKey are required; everything else is optional and secure-by-default. This page is the field-by-field reference;
for the task-oriented walkthrough see Configuration.
ClientConfig
Prop
Type
HttpTransportCustomizer and HttpRoundTripperProvider are mutually exclusive. If both are set,
HttpRoundTripperProvider wins (and a WARN reminds you that TLS is then entirely your responsibility). See
Configuration → customizing the HTTP client.
ValidationMode
ValidationMode controls what happens when a request body fails the built-in struct
validation before it is sent.
| Constant | Behavior |
|---|---|
SoftValidation | Default. Validation failures are logged as warnings; the request still goes out. |
HardValidation | Validation failures become an error and the request is not sent. |
DisableValidation | No validation is performed. |
APIStyle
APIStyle selects which controller API style the client uses. The zero value probes the controller over the
network at construction time; pinning a style skips that probe and enables fully offline construction (pair it with
SkipSystemInfo: true).
| Constant | Behavior |
|---|---|
APIStyleAuto | Default. Auto-detect by probing the controller. |
APIStyleNew | Force the new (UniFi OS / proxy) style without probing. |
APIStyleOld | The legacy classic style — unsupported; NewClient returns ErrOldStyleUnsupported. |
func exampleOffline() (unifi.Client, error) {
return unifi.NewClient(&unifi.ClientConfig{
URL: "https://unifi.example.com",
APIKey: "your-api-key",
APIStyle: unifi.APIStyleNew, // pin the style; skip the probe
SkipSystemInfo: true, // skip the eager system-info call
})
}Logging
The client logs through the Logger interface (10 leveled methods: Trace/Debug/Info/Warn/Error and
their *f formatting variants). When ClientConfig.Logger is nil the client uses an slog-backed default at
InfoLevel. Two constructors are provided:
| Constructor | Returns |
|---|---|
NewDefaultLogger(level LoggingLevel) | A log/slog text logger to stderr. DisabledLevel yields a no-op logger. |
NewSlogLogger(l *slog.Logger) | Wraps your own *slog.Logger in the Logger interface. |
LoggingLevel values, in order: DisabledLevel, TraceLevel, DebugLevel, InfoLevel (default), WarnLevel,
ErrorLevel.
func exampleConfig() (unifi.Client, error) {
return unifi.NewClient(&unifi.ClientConfig{
URL: "https://unifi.example.com",
APIKey: "your-api-key",
Timeout: 30 * time.Second,
SkipVerifySSL: false, // verify certificates (secure default)
ValidationMode: unifi.HardValidation, // reject invalid request bodies
APIStyle: unifi.APIStyleAuto, // probe the controller (default)
Logger: unifi.NewDefaultLogger(unifi.WarnLevel),
UserAgent: "my-app/1.0",
})
}For the full Logger and ClientConfig godoc see
ClientConfig and
Logger. For deeper how-tos see
Logging and Validation.