# Go SDK

[View original](https://ittybit.com/sdks/go)

## Usage

Instantiate and use the client with the following:

```go
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.

```go
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:

```go
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).

```go
// 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
* [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
* [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)

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

```go
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:

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

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