Go SDK usage

How to use the Go SDK to call for and retrieve flag details.

Published on: 14 May 2025

RocketFlag Go SDK Documentation

This guide will help you get started with integrating RocketFlag feature flags into your Go applications.

What is RocketFlag?

RocketFlag is a powerful feature flag service that allows you to manage your application’s features remotely without deploying new code. This SDK provides a convenient way to interact with the RocketFlag API from your Go applications.

Installation

To start using the RocketFlag Go SDK, you’ll first need to install it using go get. Open your terminal and run the following command:

go get https://github.com/rocketflag/go-sdk

This command will download and install the necessary SDK files into your Go workspace.

Getting Started: Basic Usage

Once the SDK is installed, you can start using it in your Go application. Here’s a basic example of how to initialise the client and retrieve a feature flag:

package main

import (
	"context" // Typically used for request-scoped values, cancellation signals, and deadlines.
	"fmt"
	"log"

	rocketflag "https://github.com/rocketflag/go-sdk" // Import the RocketFlag SDK package
)

func main() {
	// 1. Initialise the RocketFlag client
	// This creates a new client with default configurations.
	rf := rocketflag.NewClient()

	// 2. Define a UserContext (optional, but good practice)
	// For this basic example, we'll pass an empty UserContext.
	// This context can be used to pass user-specific attributes for targeted flag evaluation.
	userContext := rocketflag.UserContext{}

	// 3. Get a specific flag
	// Replace "your-flag-key" with the actual key of the flag you want to retrieve.
	flagKey := "your-flag-key"
	flag, err := rf.GetFlag(flagKey, userContext)
	if err != nil {
		// If there's an error (e.g., network issue, flag not found), log it and exit.
		log.Fatalf("Error fetching flag '%s': %v", flagKey, err)
	}

	// 4. Use the flag's value
	// The 'flag' variable will contain information about the feature flag,
	// including whether it's enabled or disabled.
	// How you use the flag depends on its type and your application logic.
	// For example, if it's a boolean flag:
	// if flag.IsEnabled() {
	//     fmt.Println("Feature associated with", flagKey, "is enabled!")
	//     // Execute code for the enabled feature
	// } else {
	//     fmt.Println("Feature associated with", flagKey, "is disabled.")
	//     // Execute alternative code or do nothing
	// }

	// For now, let's just print the flag details:
	fmt.Printf("Flag Details for '%s': %+v\n", flagKey, flag)
}

Explanation:

Import necessary packages: We import context, fmt for printing, log for error handling, and the rocketflag/go-sdk itself.
Initialise Client: rocketflag.NewClient() creates a new instance of the RocketFlag client with default settings.
Get a Flag: rf.GetFlag("flag-id", rocketflag.UserContext{}) fetches the state of the flag identified by "flag-id".
- The first argument is the unique key of the flag you want to retrieve. You create this key in your RocketFlag dashboard.
- The second argument, rocketflag.UserContext{}, is used to provide context about the user for whom the flag is being evaluated. For basic usage, an empty context is sufficient. We’ll explore this more in the “Working with Cohorts” section.
Error Handling: It’s crucial to check for errors after API calls.
Using the Flag: The flag variable returned will contain the details of your feature flag, allowing you to control features in your application.

Working with Cohorts

Cohorts allow you to enable features for specific segments of your users. To use cohorts, you first need to define them in your RocketFlag dashboard.

Once your cohorts are set up in the RocketFlag console, you can specify which cohort a user belongs to by passing information in the UserContext when calling GetFlag.

The UserContext is a map where you can pass relevant attributes. For example, if you have a cohort defined by email addresses, you can pass the user’s email like so:

package main

import (
	"context"
	"fmt"
	"log"

	rocketflag "github.com/rocketflag/go-sdk"
)

func main() {
	rf := rocketflag.NewClient()

	flagKey := "your-targeted-flag-key"

	// Example: User belongs to the 'beta-testers' cohort via their email
	userContextForBetaTester := rocketflag.UserContext{"cohort": "user@example.com"} // Assuming "user@example.com" is part of a defined cohort

	flag, err := rf.GetFlag(flagKey, userContextForBetaTester)
	if err != nil {
		log.Fatalf("Error fetching flag '%s' for user: %v", flagKey, err)
	}

	fmt.Printf("Flag '%s' for user 'user@example.com': %+v\n", flagKey, flag)

	// Example: User not in a specific cohort or different attribute
	userContextForRegularUser := rocketflag.UserContext{"userId": "regularUser123"}

	flagRegular, errRegular := rf.GetFlag(flagKey, userContextForRegularUser)
	if errRegular != nil {
		log.Fatalf("Error fetching flag '%s' for regular user: %v", flagKey, errRegular)
	}

	fmt.Printf("Flag '%s' for regular user: %+v\n", flagKey, flagRegular)
}

In this example, rocketflag.UserContext{"cohort": "user@example.com"} tells RocketFlag to evaluate the flag for a user identified by "user@example.com", potentially matching them to a cohort you’ve configured in the RocketFlag dashboard.

Advanced Configuration

The RocketFlag Go SDK allows you to customise the client’s behavior by passing options to NewClient().

Custom HTTP Client

If your application uses a custom http.Client (for example, with specific timeouts, transport settings, or middleware), you can instruct the RocketFlag SDK to use it.

import (
	"net/http"
	"time"

	rocketflag "github.com/rocketflag/go-sdk"
)

// Example: Create a custom HTTP client
customHTTPClient := &http.Client{
	Timeout: 10 * time.Second, // Set a custom timeout
}

// Pass the custom client to the RocketFlag client
rfClient := rocketflag.NewClient(rocketflag.WithHTTPClient(customHTTPClient))

// Now rfClient will use your customHTTPClient for all API requests.

Custom API Version

By default, the SDK uses the latest API version it supports (currently version 1). If you need to target a specific version of the RocketFlag API (e.g., for compatibility reasons or to access new features not yet default in the SDK), you can specify it during client initialisation.

import rocketflag "github.com/rocketflag/go-sdk"

// Initialise the client to use API version "v2"
rfClient := rocketflag.NewClient(rocketflag.WithVersion("v2"))

// rfClient will now make requests to version "v2" of the RocketFlag API.

Note: Ensure that the API version you specify is valid and supported.

Custom API URL

For self-hosted instances of RocketFlag or when using a proxy, you might need to change the base URL the SDK communicates with. The default is https://api.rocketflag.app.

import rocketflag "github.com/rocketflag/go-sdk"

// Initialise the client to use a custom API URL
customURL := "https://my-rocketflag-instance.example.com"
rfClient := rocketflag.NewClient(rocketflag.WithAPIURL(customURL))

// rfClient will now send requests to your customURL.

Chaining Configuration Options

You can combine multiple configuration options when creating the client. Simply pass them as additional arguments to NewClient().

import (
	"net/http"
	"time"

	rocketflag "github.com/rocketflag/go-sdk"
)

// Example: Custom HTTP client
customHTTPClient := &http.Client{
	Timeout: 15 * time.Second,
}

// Initialise client with multiple custom options
rfClient := rocketflag.NewClient(
	rocketflag.WithHTTPClient(customHTTPClient),
	rocketflag.WithVersion("v2"),
	rocketflag.WithAPIURL("https://internal.api.example.com"),
)

// This rfClient will use the custom HTTP client, target API v2, and send requests to "https://internal.api.example.com".