Go SDK Concepts: Clients

Understanding how to use and configure clients is fundamental to interacting with the OurAwesomeAPI services from your Go applications. The Go SDK provides a flexible and robust client implementation that can be customized to suit various needs.

The Core Client

At the heart of the Go SDK is the Client struct. This struct holds the necessary configuration and methods to communicate with the API. You'll typically instantiate a client and then use its methods to perform operations.

Default Client Instantiation

The simplest way to get started is by creating a default client. This client will use sensible defaults, such as no authentication and a default API endpoint. However, for most practical applications, you'll want to configure it further.

package main

import (
    "fmt"
    "log"
    "awesomeapi-go-sdk/client"
)

func main() {
    // Create a default client
    c, err := client.NewClient()
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    fmt.Println("Client created successfully!")
    // Now you can use 'c' to make API calls
}
        

Client Configuration

The Go SDK offers several ways to configure your client, allowing you to tailor its behavior. Configuration options include setting the API endpoint, managing authentication, configuring HTTP transport settings, and more.

Using Options

The recommended way to configure the client is by using functional options. This pattern makes the client instantiation clear and extensible.

Common Configuration Options:

• client.WithBaseURL(url string): Sets the base URL for API requests.
• client.WithAPIKey(key string): Configures API key authentication.
• client.WithToken(token string): Configures bearer token authentication.
• client.WithHTTPClient(httpClient *http.Client): Allows you to provide a custom *http.Client, giving you fine-grained control over HTTP transport, timeouts, proxies, etc.
• client.WithLogger(logger interface{}): Integrates a custom logger.

Example with Options:

Here's an example demonstrating how to configure a client with a custom base URL and API key:

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"
    "awesomeapi-go-sdk/client"
)

func main() {
    customHTTPClient := &http.Client{
        Timeout: 30 * time.Second,
        Transport: &http.Transport{
            // Configure proxy, TLS settings, etc. here if needed
        },
    }

    c, err := client.NewClient(
        client.WithBaseURL("https://api.example.com/v2"),
        client.WithAPIKey("YOUR_SECURE_API_KEY"),
        client.WithHTTPClient(customHTTPClient),
    )
    if err != nil {
        log.Fatalf("Failed to create configured client: %v", err)
    }

    fmt.Println("Configured client created successfully!")
    // Use 'c' for API calls to api.example.com/v2
}
        

Custom HTTP Transport

For advanced scenarios, you might need to customize the underlying HTTP transport. This could involve setting up proxies, configuring TLS settings, or adding custom headers to every request.

You can achieve this by creating your own *http.Client and passing it to the client.WithHTTPClient option.

Client Methods

Once you have a client instance, you can access various methods to interact with different API endpoints. These methods are typically organized by resource or functionality.

For instance, if you want to fetch user data, you might use a method like:

// Assuming 'c' is your configured client
users, err := c.Users.List(context.Background(), &client.ListUsersParams{
    Limit: 10,
})
if err != nil {
    log.Fatalf("Error fetching users: %v", err)
}
// Process the 'users' response
        

Refer to the API Reference for a comprehensive list of available client methods and their parameters.