Introduction

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

Instrument your applications with App Configuration SDKs, and use the App Configuration dashboard or App Configuration administrator API to define features flags, which are organized into collections and targeted to segments. Change feature flag states in the cloud to activate or deactivate features in your application or environment, often without restarting.

App Owners - Roll out features by segment and independent from code deployments.
Developers - Reduce source code branch complexity and troublesome merges by including untested or unfinished features behind a feature flag in your master branch.
Testers - Increase confidence that new features will smoothly transition to production by testing there. Use flags to activate untested features only for testers and QA personnel until it's time to release.

Before you begin

Make sure that you have access to a paid IBM Cloud account.

Learn more about App Configuration.

SDKs

For more information about installation and technical concepts, see the 'README' document in the SDK.

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
  "github.com/IBM/appconfiguration-go-admin-sdk/appconfigurationv1"
)

Go get

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

View on GitHub

https://github.com/IBM/appconfiguration-go-admin-sdk

Endpoint URLs

The following URLs represents the base URLs for the App Configuration API endpoints. When you call the API, use the URL that corresponds to the region where your service instance is deployed. Add the path for each method to form the complete API endpoint for your requests.

Dallas: https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Washington DC: https://us-east.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
London: https://eu-gb.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Sydney: https://au-syd.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Frankfurt: https://eu-de.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Toronto: https://ca-tor.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Tokyo: https://jp-tok.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Osaka: https://jp-osa.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Madrid: https://eu-es.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Sao Paulo: https://br-sao.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Montreal: https://ca-mon.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Chennai: https://in-che.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Mumbai: https://in-mum.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}

If you have enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs.

Dallas: https://private.us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Washington DC: https://private.us-east.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
London: https://private.eu-gb.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Sydney: https://private.au-syd.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Frankfurt: https://private.eu-de.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Toronto: https://private.ca-tor.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Tokyo: https://private.jp-tok.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Osaka: https://private.jp-osa.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Madrid: https://private.eu-es.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Sao Paulo: https://private.br-sao.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Montreal: https://private.ca-mon.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Chennai: https://private.in-che.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}
Mumbai : https://private.in-mum.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}

The following table details the location where the App Configuration actions run, data stored and replicated:

| Location | Location where App Configuration actions run | Data is stored in | Data is replicated to | |-------------|------|--------|-------| | Dallas | All App Configuration actions run in the Dallas (us-south) location. | All metadata for the app's features are stored in the Dallas (us-south) location. | Data is replicated between three zones within us-south for high-availability. | | Washington DC | All App Configuration actions run in the Washington DC (us-east) location. | All metadata for the app's features are stored in the Washington DC (us-east) location. | Data is replicated between three zones within us-east for high-availability. | | London | All App Configuration actions run in the London (eu-gb) location. | All metadata for the app's features are stored in the London (eu-gb) location. | Data is replicated between three zones within eu-gb for high-availability. | | Sydney | All App Configuration actions run in the Sydney (au-syd) location. | All metadata for the app's features are stored in the Sydney (au-syd) location. | Data is replicated between three zones within au-syd for high-availability. | | Frankfurt | All App Configuration actions run in the Frankfurt (eu-de) location. | All metadata for the app's features are stored in the Frankfurt (eu-de) location. | Data is replicated between three zones within eu-de for high-availability. | | Toronto | All App Configuration actions run in the Toronto (ca-tor) location. | All metadata for the app's features are stored in the Toronto (ca-tor) location. | Data is replicated between three zones within ca-tor for high-availability. | | Tokyo | All App Configuration actions run in the Tokyo (jp-tok) location. | All metadata for the app's features are stored in the Tokyo (jp-tok) location. | Data is replicated between three zones within jp-tok for high-availability. | | Osaka | All App Configuration actions run in the Osaka (jp-osa) location. | All metadata for the app's features are stored in the Osaka (jp-osa) location. | Data is replicated between three zones within jp-osa for high-availability. | | Madrid | All App Configuration actions run in the Madrid (eu-es) location. | All metadata for the app's features are stored in the Madrid (eu-es) location. | Data is replicated between three zones within eu-es for high-availability. | | Sao Paulo | All App Configuration actions run in the Sao Paulo (br-sao) location. | All metadata for the app's features are stored in the Sao Paulo (br-sao) location. | Data is replicated between three zones within br-sao for high-availability. | | Montreal | All App Configuration actions run in the Montreal (ca-mon) location. | All metadata for the app's features are stored in the Montreal (ca-mon) location. | Data is replicated between three zones within ca-mon for high-availability. | | Chennai | All App Configuration actions run in the Chennai (in-che) location. | All metadata for the app's features are stored in the Chennai (in-che) location. | Data is replicated between three zones within in-che for high-availability. | | Mumbai | All App Configuration actions run in the Mumbai (in-mum) location. | All metadata for the app's features are stored in the Mumbai (in-mum) location. | Data is replicated between three zones within in-mum for high-availability. |

Base URL

https://{region}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}

Example request to a Dallas endpoint:

curl -H "Authorization:Bearer {token}" -X "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}"

Replace {token} and {guid} in this example with the values for your particular API call.

Example request to a Dallas endpoint:

import (
    "encoding/json"
    "fmt"
    "github.com/IBM/go-sdk-core/v5/core"
    ac "github.com/IBM/appconfiguration-go-admin-sdk/appconfigurationv1"
)

func main() {

    appConfigurationService, err := ac.NewAppConfigurationV1(&ac.AppConfigurationV1Options {
        URL: "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{guid}",
        Authenticator: & core.IamAuthenticator {
            ApiKey: "<API_KEY>",
        },
    })

    if err != nil {
        panic(err)
    }
}

Authentication

Authorization to the App Configuration API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

To work with the API, include a valid IAM token in each outgoing request to the service. You can generate an access token by first creating an API key and then exchanging your API key for an IBM Cloud IAM token. By default, the IAM access token have a lifetime of 60 minutes. See Managing access token expiration to decrease the IAM access token lifetime.

Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.

When you use the SDK, configure an IAM authenticator with an IBM Cloud IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can configure an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key.
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with your IAM API key.

Setting client options through external configuration

Example environment variables, where {SERVICE_URL} is the endpoint URL and {API_KEY} is your IAM API key

export APP_CONFIGURATION_URL={SERVICE_URL}
export APP_CONFIGURATION_AUTH_TYPE=iam
export APP_CONFIGURATION_APIKEY={API_KEY}

Example of constructing the service client

import {
     ac "github.com/IBM/appconfiguration-go-admin-sdk/appconfigurationv1"
}
...
serviceClientOptions := &ac.AppConfigurationV1Options{}
serviceClient, err := ac.NewAppConfigurationV1UsingExternalConfig(serviceClientOptions)

Auditing

You can monitor API activity within your account by using the IBM Cloud Logs service. Whenever an API method is called, an event is generated that you can then track and audit from within IBM Cloud Logs. The specific event type is listed for each individual method.

For more information about how to track App Configuration activity, see Auditing events for App Configuration.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 2xx response always indicates success. A 4xx type response is some sort of failure, and a 5xx type response usually indicates an internal system error.

| HTTP status code | Description | Recovery | |------------------|-------------|----------| | 200 | Success | The request was successful. | | 201 | Success | The resource was successfully created and added to your IBM Cloud account. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized to access the apps. Check that you have the correct access credentials and permissions. | | 404 | Not Found | The requested resource could not be found. | | 408 | Request timeout | The connection to the server timed out. Wait a few minutes, then try again. | | 409 | Conflict | The entity is already in the requested state. | | 429 | Too Many Requests | Too many requests have been made within a time window. Wait before calling the API again. | | 500 | Internal Server Error | IBM Cloud App Configuration is not available. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support. | | 503 | Service Temporarily Unavailable | IBM Cloud App Configuration could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support. |

Example error handling

import ac "github.com/IBM/appconfiguration-go-admin-sdk/appconfigurationv1"

// Instantiate a service
appConfigurationService, err := ac.NewAppConfigurationV1(&ac.AppConfigurationV1Options)

// Check for errors
if err != nil {
  panic(err)
}

// Call a method
result, response, err := appConfigurationService.MethodName(&methodOptions)

// Check for errors
if err != nil {
  panic(err)
}

App Configuration | IBM Cloud API Docs