Go SDK

The Ittybit Go library provides convenient access to the Ittybit API from Go.

Usage

Instantiate and use the client with the following:

package example

import (
    client "github.com/ittybit/sdk-go/client"
    option "github.com/ittybit/sdk-go/option"
    context "context"
)

func do() () {
    ittybit := client.NewClient(
        option.WithToken(
            "<ITTYBIT_API_KEY>",
        ),
    )
    ittybit.Automations.Create(
        context.TODO(),
    )
}

Environments

You can choose between different environments by using the option.WithBaseURL option. You can configure any arbitrary base URL, which is particularly useful in test environments.

ittybit := client.NewClient(
    option.WithBaseURL(ittybit.Environments.Default),
)

Errors

Structured error types are returned from API calls that return non-success status codes. These errors are compatible with the errors.Is and errors.As APIs, so you can access the error like so:

response, err := ittybit.Automations.Create(...)
if err != nil {
    var apiError *core.APIError
    if errors.As(err, apiError) {
        // Do something with the API error ...
    }
    return err
}

Request Options

A variety of request options are included to adapt the behavior of the library, which includes configuring authorization tokens, or providing your own instrumented *http.Client.

These request options can either be specified on the client so that they're applied on every request, or for an individual request, like so:

Providing your own *http.Client is recommended. Otherwise, the http.DefaultClient will be used, and your client will wait indefinitely for a response (unless the per-request, context-based timeout is used).

// Specify default options applied on every request.
ittybit := client.NewClient(
    option.WithToken("<ITTYBIT_API_KEY>"),
    option.WithHTTPClient(
        &http.Client{
            Timeout: 5 * time.Second,
        },
    ),
)

// Specify options for an individual request.
response, err := ittybit.Automations.Create(
    ...,
    option.WithToken("<ITTYBIT_API_KEY>"),
)

Advanced

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the option.WithMaxAttempts option to configure this behavior for the entire client or an individual request:

ittybit := client.NewClient(
    option.WithMaxAttempts(1),
)

response, err := ittybit.Automations.Create(
    ...,
    option.WithMaxAttempts(1),
)

Timeouts

Setting a timeout for each individual request is as simple as using the standard context library. Setting a one second timeout for an individual API call looks like the following:

ctx, cancel := context.WithTimeout(ctx, time.Second)
defer cancel()

response, err := ittybit.Automations.Create(ctx, ...)