appconfiguration-go-sdk

IBM Cloud App Configuration Go server SDK

IBM Cloud App Configuration SDK is used to perform feature flag and property evaluation based on the configuration on IBM Cloud App Configuration service.

Table of Contents

• Overview
• Installation
  • go get command
  • Go modules
• Using the SDK
• License

Overview

IBM Cloud App Configuration is a centralized feature management and configuration service on IBM Cloud for use with web and mobile applications, microservices, and distributed environments.

Instrument your applications with App Configuration Go SDK, and use the App Configuration dashboard, API or CLI to define feature flags or properties, organized into collections and targeted to segments. Change feature flag states in the cloud to activate or deactivate features in your application or environment, when required. You can also manage the properties for distributed applications centrally.

Installation

The current version of this SDK: 0.2.0

There are a few different ways to download and install the IBM App Configuration Go SDK project for use by your Go application:

go get command

Use this command to download and install the SDK (along with its dependencies) to allow your Go application to use it:

go get -u github.com/IBM/appconfiguration-go-sdk

Go modules

If your application is using Go modules, you can add a suitable import to your Go application, like this:

import (
	AppConfiguration "github.com/IBM/appconfiguration-go-sdk/lib"
)

then run go mod tidy to download and install the new dependency and update your Go application's go.mod file.

Using the SDK

Initialize the sdk to connect with your App Configuration service instance.

appConfiguration := AppConfiguration.GetInstance()
appConfiguration.Init("region", "guid", "apikey")

collectionId := "airlines-webapp"
environmentId := "dev"
appConfiguration.SetContext(collectionId, environmentId)

• region : Region name where the App Configuration service instance is created. Use
  • AppConfiguration.REGION_US_SOUTH for Dallas
  • AppConfiguration.REGION_EU_GB for London
  • AppConfiguration.REGION_AU_SYD for Sydney
• guid : Instance Id of the App Configuration service. Obtain it from the service credentials section of the App Configuration dashboard.
• apikey : ApiKey of the App Configuration service. Obtain it from the service credentials section of the App Configuration dashboard.

• collectionId: Id of the collection created in App Configuration service instance under the Collections section.
• environmentId: Id of the environment created in App Configuration service instance under the Environments section.

Here, by default live update from the server is enabled. To turn off this mode see the below section

Work offline with local configuration file (Optional)

You can also work offline with local configuration file and perform feature and property related operations.

After appConfiguration.Init("region", "guid", "apikey"), follow the below steps

appConfiguration.SetContext("airlines-webapp", "dev", AppConfiguration.ContextOptions{
  ConfigurationFile:       "saflights/flights.json",
  LiveConfigUpdateEnabled: false
})

• ConfigurationFile: Path to the JSON file, which contains configuration details.
• LiveConfigUpdateEnabled: Set this value to false if the new configuration values shouldn't be fetched from the server. Make sure to provide a proper JSON file in the path. By default, this value is enabled.

Get single feature

feature, err := appConfiguration.GetFeature("online-check-in")
if err == nil {
    fmt.Println("Feature Name", feature.GetFeatureName())
    fmt.Println("Feature Id", feature.GetFeatureID())
    fmt.Println("Feature Type", feature.GetFeatureDataType())

    if (feature.IsEnabled()) {
        // feature flag is enabled
    } else {
        // feature flag is disabled
    }
}

Get all features

features, err := appConfiguration.GetFeatures()
if err == nil {
    feature := features["online-check-in"]
    
    fmt.Println("Feature Name", feature.GetFeatureName())
    fmt.Println("Feature Id", feature.GetFeatureID())
    fmt.Println("Feature Type", feature.GetFeatureDataType())
    fmt.Println("Feature is enabled", feature.IsEnabled())
}

Evaluate a feature

You can use the feature.GetCurrentValue(entityId, entityAttributes) method to evaluate the value of the feature flag. You should pass an unique entityId as the parameter to perform the feature flag evaluation. If the feature flag is configured with segments in the App Configuration service, you can set the attributes values as a map.

entityId := "john_doe"
entityAttributes := make(map[string]interface{})
entityAttributes["city"] = "Bangalore"
entityAttributes["country"] = "India"

featureVal := feature.GetCurrentValue(entityId, entityAttributes)

Get single property

property, err := appConfiguration.GetProperty("check-in-charges")
if err == nil {
    fmt.Println("Property Name", property.GetPropertyName())
    fmt.Println("Property Id", property.GetPropertyID())
    fmt.Println("Property Type", property.GetPropertyDataType())
}

Get all properties

properties, err := appConfiguration.GetProperties()
if err == nil {
    property := properties["check-in-charges"]
    
    fmt.Println("Property Name", property.GetPropertyName())
    fmt.Println("Property Id", property.GetPropertyID())
    fmt.Println("Property Type", property.GetPropertyDataType())
}

Evaluate a property

You can use the property.GetCurrentValue(entityId, entityAttributes) method to evaluate the value of the property. You should pass an unique entityId as the parameter to perform the property evaluation. If the property is configured with segments in the App Configuration service, you can set the attributes values as a map.

entityId := "john_doe"
entityAttributes := make(map[string]interface{})
entityAttributes["city"] = "Bangalore"
entityAttributes["country"] = "India"

propertyVal := property.GetCurrentValue(entityId, entityAttributes)

Supported Data types

App Configuration service allows to configure the feature flag and properties in the following data types : Boolean, Numeric, String. The String data type can be of the format of a text string , JSON or YAML. The SDK processes each format accordingly as shown in the below table.

{
  "firefox": {
    "name": "Firefox",
    "pref_url": "about:config"
  }
}

men:
  - John Smith
  - Bill Jones
women:
  - Mary Smith
  - Susan Williams

feature, err := appConfiguration.GetFeature("json-feature")
if err == nil {
  feature.GetFeatureDataType() // STRING
  feature.GetFeatureDataFormat() // JSON
  
  // Example (traversing the returned map)
  result := feature.GetCurrentValue(entityID, entityAttributes) // JSON value is returned as a Map
  result.(map[string]interface{})["key"] // returns the value of the key
}

feature, err := appConfiguration.GetFeature("yaml-feature")
if err == nil {
  feature.GetFeatureDataType() // STRING
  feature.GetFeatureDataFormat() // YAML
  
  // Example (traversing the returned map)
  result := feature.GetCurrentValue(entityID, entityAttributes) // YAML value is returned as a Map
  result.(map[string]interface{})["key"] // returns the value of the key
}

property, err := appConfiguration.GetProperty("json-property")
if err == nil {
  property.GetPropertyDataType() // STRING
  property.GetPropertyDataFormat() // JSON

  // Example (traversing the returned map)
  result := property.GetCurrentValue(entityID, entityAttributes) // JSON value is returned as a Map
  result.(map[string]interface{})["key"] // returns the value of the key
}

property, err := appConfiguration.GetProperty("yaml-property")
if err == nil {
  property.GetPropertyDataType() // STRING
  property.GetPropertyDataFormat() // YAML

  // Example (traversing the returned map)
  result := property.GetCurrentValue(entityID, entityAttributes) // YAML value is returned as a Map
  result.(map[string]interface{})["key"] // returns the value of the key
}

Set listener for feature or property data changes

To listen to the configurations changes in your App Configuration service instance, implement the RegisterConfigurationUpdateListener event listener as mentioned below

appConfiguration.RegisterConfigurationUpdateListener(func () {
    fmt.Println("Get your feature/property value now ")
})

Fetch latest data

appConfiguration.FetchConfigurations()

Enable debugger (Optional)

appConfiguration.EnableDebug(true)

Examples

Try this sample application in the examples folder to learn more about feature and property evaluation.

License

This project is released under the Apache 2.0 license. The license's full text can be found in LICENSE