Go SDK

The Staqr Go SDK provides idiomatic Go support with native HTTP client for high-performance microservices and cloud-native applications.

Installation

Go Modules

# Staqr Platform API
go get github.com/staqr/api-client-go

# Commerce APIs
go get github.com/staqr/commerce-v1-go  # Recommended - structured APIs
go get github.com/staqr/commerce-v2-go  # Generic CRUD
go get github.com/staqr/commerce-v0-go  # Legacy

From Local SDK

# Add to go.mod
require github.com/staqr/api-client-go v0.0.0

replace github.com/staqr/api-client-go => ./sdks/staqr-go

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    staqr "github.com/staqr/api-client-go"
)

func main() {
    ctx := context.Background()

    // Configure the client
    config := staqr.NewConfiguration()
    config.Host = "my.staqr.com"
    config.Scheme = "https"
    config.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("STAQR_API_KEY"))
    config.AddDefaultHeader("x-seller-id", os.Getenv("STAQR_SELLER_ID"))

    client := staqr.NewAPIClient(config)

    // List flows
    flows, _, err := client.FlowsApi.ListFlows(ctx).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }

    for _, flow := range flows {
        fmt.Printf("Flow: %s\n", *flow.DisplayName)
    }
}

Authentication

API Key Authentication

import staqr "github.com/staqr/api-client-go"

config := staqr.NewConfiguration()
config.Host = "my.staqr.com"
config.Scheme = "https"
config.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("STAQR_API_KEY"))
config.AddDefaultHeader("x-seller-id", os.Getenv("STAQR_SELLER_ID"))

client := staqr.NewAPIClient(config)

OAuth2 (Commerce APIs)

import commerce "github.com/staqr/commerce-v1-go"

// For Commerce Direct access (Keycloak OAuth2)
config := commerce.NewConfiguration()
config.Host = "commerce.staqr.com"
config.Scheme = "https"
config.AddDefaultHeader("Authorization", "Bearer "+commerceOAuthToken)
config.AddDefaultHeader("X-Tenant", "YOUR_TENANT_CODE")

client := commerce.NewAPIClient(config)

Available Packages

Module	API	Install Command
github.com/staqr/api-client-go	Staqr Platform	go get github.com/staqr/api-client-go
github.com/staqr/commerce-v1-go	Commerce v1 (Structured)	go get github.com/staqr/commerce-v1-go
github.com/staqr/commerce-v2-go	Commerce v2 (Generic CRUD)	go get github.com/staqr/commerce-v2-go
github.com/staqr/commerce-v0-go	Commerce v0 (Legacy)	go get github.com/staqr/commerce-v0-go

Common Operations

Working with Customers (Commerce)

package main

import (
    "context"
    "fmt"

    commerce "github.com/staqr/commerce-v1-go"
)

func main() {
    ctx := context.Background()
    client := commerce.NewAPIClient(config)

    // List customers
    customers, _, err := client.CustomerManagementApi.ListCustomers(ctx).Execute()
    if err != nil {
        panic(err)
    }

    // Get customer by code
    customer, _, err := client.CustomerManagementApi.GetCustomerByCode(ctx, "CUST001").Execute()
    if err != nil {
        panic(err)
    }

    fmt.Printf("Customer: %s\n", *customer.Code)

    // Create customer
    newCustomer := commerce.NewCustomerDto()
    newCustomer.SetCode("CUST002")
    newCustomer.SetDescription("New Customer")

    created, _, err := client.CustomerManagementApi.CreateCustomer(ctx).CustomerDto(*newCustomer).Execute()
    if err != nil {
        panic(err)
    }
}

Context with Timeout

import (
    "context"
    "time"
)

// Create context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

flows, _, err := client.FlowsApi.ListFlows(ctx).Execute()

Error Handling

import (
    "errors"

    staqr "github.com/staqr/api-client-go"
)

flow, resp, err := client.FlowsApi.GetFlow(ctx, "invalid-id").Execute()
if err != nil {
    var apiErr *staqr.GenericOpenAPIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API Error: %s\n", apiErr.Error())
        fmt.Printf("Status Code: %d\n", resp.StatusCode)
        fmt.Printf("Response Body: %s\n", string(apiErr.Body()))
    }
    return
}

HTTP Server Integration

Gin Framework

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    staqr "github.com/staqr/api-client-go"
)

var client *staqr.APIClient

func init() {
    config := staqr.NewConfiguration()
    config.Host = "my.staqr.com"
    config.Scheme = "https"
    config.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("STAQR_API_KEY"))
    config.AddDefaultHeader("x-seller-id", os.Getenv("STAQR_SELLER_ID"))
    client = staqr.NewAPIClient(config)
}

func main() {
    r := gin.Default()

    r.GET("/flows", func(c *gin.Context) {
        flows, _, err := client.FlowsApi.ListFlows(c.Request.Context()).Execute()
        if err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, flows)
    })

    r.Run(":8080")
}

Standard Library

package main

import (
    "encoding/json"
    "net/http"

    staqr "github.com/staqr/api-client-go"
)

func handleFlows(w http.ResponseWriter, r *http.Request) {
    flows, _, err := client.FlowsApi.ListFlows(r.Context()).Execute()
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(flows)
}

func main() {
    http.HandleFunc("/flows", handleFlows)
    http.ListenAndServe(":8080", nil)
}

Go Requirements

• Go 1.21 or higher (recommended)
• Go 1.18+ (minimum for generics support)

Dependencies

The SDK uses:

• Standard library net/http for HTTP client
• No external dependencies (pure Go)

Concurrency Patterns

Parallel API Calls

import (
    "context"
    "sync"
)

func fetchAllData(ctx context.Context, client *staqr.APIClient) error {
    var wg sync.WaitGroup
    errChan := make(chan error, 2)

    wg.Add(2)

    // Fetch flows
    go func() {
        defer wg.Done()
        _, _, err := client.FlowsApi.ListFlows(ctx).Execute()
        if err != nil {
            errChan <- err
        }
    }()

    // Fetch connections
    go func() {
        defer wg.Done()
        _, _, err := client.ConnectionsApi.ListConnections(ctx).Execute()
        if err != nil {
            errChan <- err
        }
    }()

    wg.Wait()
    close(errChan)

    for err := range errChan {
        if err != nil {
            return err
        }
    }

    return nil
}

Examples

See the examples directory for complete usage examples:

• Basic API calls
• HTTP server integration
• CLI application
• Error handling patterns
• Concurrent operations

API Reference

For complete API documentation, see:

• Staqr Platform API Reference
• Commerce API Reference

Troubleshooting

TLS/SSL Issues

import (
    "crypto/tls"
    "net/http"
)

// Development only!
config := staqr.NewConfiguration()
config.HTTPClient = &http.Client{
    Transport: &http.Transport{
        TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
    },
}

Custom HTTP Client

import (
    "net/http"
    "time"
)

httpClient := &http.Client{
    Timeout: 30 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:        100,
        MaxIdleConnsPerHost: 10,
        IdleConnTimeout:     90 * time.Second,
    },
}

config := staqr.NewConfiguration()
config.HTTPClient = httpClient

Debug Logging

config := staqr.NewConfiguration()
config.Debug = true  // Enables request/response logging