Go SDK Documentation

Overview

The Go SDK provides idiomatic Go bindings for interacting with our API. It abstracts HTTP communication, authentication, error handling, and pagination into convenient Go types and functions.

Authentication

All requests must include an API token. The SDK reads the token from the API_TOKEN environment variable or can be set programmatically.

import "github.com/example/sdk"

func main() {
    client := sdk.NewClient(sdk.WithAPIKey("YOUR_API_TOKEN"))
    // Use client...
}

Error Handling

The SDK returns Go errors. API errors are wrapped in sdk.APIError which provides HTTP status, code, and message.

resp, err := client.GetResource(ctx, id)
if err != nil {
    if apiErr, ok := err.(*sdk.APIError); ok {
        fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
    } else {
        fmt.Println("Unexpected error:", err)
    }
}

Rate Limiting

The SDK automatically respects Retry-After headers. You can also configure a custom backoff strategy.

client := sdk.NewClient(
    sdk.WithAPIKey(os.Getenv("API_TOKEN")),
    sdk.WithRetryPolicy(sdk.ExponentialBackoff(5)),
)

Concurrency

All SDK methods are safe for concurrent use. Internally, the client reuses an HTTP transport with connection pooling.

var wg sync.WaitGroup
for i := 0; i < 10; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        res, _ := client.FetchData(ctx, id)
        fmt.Println(res)
    }(i)
}
wg.Wait()

Pagination

List endpoints return a Pager to iterate over pages lazily.

pager := client.ListItems(ctx, sdk.ListOptions{PageSize: 50})
for pager.Next() {
    for _, item := range pager.Items() {
        fmt.Println(item.ID)
    }
}
if err := pager.Err(); err != nil {
    log.Fatal(err)
}