IBM Cloud API Docs

Introduction

Last updated: 2023-11-10

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.

Table 1. List of App Configuration server, client, and admin SDKs
Server SDKs Client SDKs Admin SDKs
Node SDK
Documentation		 Android SDK
Documentation		 Go Admin SDK
Python SDK
Documentation		 JavaScript SDK
Documentation
Go SDK
Documentation		 React SDK
Documentation
Java SDK
Documentation

Installation

The code examples on this tab use the IBM Cloud App Configuration admin SDK for Go.

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

For more installation options, view this project in GitHub.

Endpoints 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}

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}

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

Table 2. Location where App Configuration actions run, data storage and replication
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.

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} in this example with the values for your particular API call.

Endpoint URL

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

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.

To generate an access token from your API key, use the following cURL command.

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 IBM Cloud API key.

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.

Example API request

curl -H "Authorization:Bearer {TOKEN}" -X "{BASE_URL}/{METHOD}"

Replace {TOKEN} with your IAM access token.

Example that initializes the SDK programmatically.

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

func main() {
    appconfigurationApi, err := ac.NewAppConfigurationV1(&ac.AppConfigurationV1Options {
        URL: "{BASE_URL}",
        Authenticator: &core.IamAuthenticator {
            ApiKey: "{API_KEY}",
        },
    })

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

Replace {API_KEY} with your IBM Cloud API key. Replace {BASE_URL} with the endpoint URL for your instance.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. 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.

Table 3. List of HTTP response codes
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 "github.com/IBM/appconfiguration-go-admin-sdk/appconfigurationv1"

// Instantiate a service
appconfigurationApi, err := appconfigurationv1.NewAppConfigurationV1(options)

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

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

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

Versioning

Specify the version to use on API requests with the version parameter when you create the service instance. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

API requests require a major version in the path (/v1/).

Methods

Get list of Environments

List all the environments in the App Configuration service instance.

List all the environments in the App Configuration service instance.

GET /environments
(appConfiguration *AppConfigurationV1) ListEnvironments(listEnvironmentsOptions *ListEnvironmentsOptions) (result *EnvironmentList, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) ListEnvironmentsWithContext(ctx context.Context, listEnvironmentsOptions *ListEnvironmentsOptions) (result *EnvironmentList, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.environments.list

Auditing

Calling this method generates the following auditing event.

  • apprapp.environments.list

Request

Instantiate the ListEnvironmentsOptions struct and set the fields to provide parameter values for the ListEnvironments method.

Query Parameters

  • expand
    boolean

    If set to true, returns expanded view of the resource details.

  • sort
    string

    Sort the environment details based on the specified attribute.

    Allowable values: [created_time,updated_time,id,name (default)]

  • tags
    string

    Filter the resources to be returned based on the associated tags. Specify the parameter as a list of comma separated tags. Returns resources associated with any of the specified tags.

    Example: version 1.1, pre-release

  • include
    string[]

    Include feature, property, snapshots details in the response.

    Allowable values: [features,properties,snapshots]

  • limit
    integer

    The number of records to retrieve. By default, the list operation return the first 10 records. To retrieve different set of records, use limit with offset to page through the available records.

    Possible values: 1 ≤ value ≤ 100

    Default: 10

  • offset
    integer

    The number of records to skip. By specifying offset, you retrieve a subset of items that starts with the offset value. Use offset with limit to page through the available records.

    Possible values: value ≥ 0

    Default: 0

  • search
    string

    Searches for the provided keyword and returns the appropriate row with that value. Here the search happens on the '[Name OR Tag]' of the entity

    Example: test tag

parameter

WithContext method only

ListEnvironmentsOptions

The ListEnvironments options.

  • curl --request GET --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments?expand=true' --header 'Authorization: Bearer {TOKEN}' 

  • listEnvironmentsOptionsModel := appConfigurationServiceInstance.NewListEnvironmentsOptions() 
 result, response, err := appConfigurationServiceInstance.ListEnvironments(listEnvironmentsOptionsModel)

Response

Response Body

EnvironmentList

List of all environments.

EnvironmentList

List of all environments.

Examples:
View

Status Code

  • 200

    Successfully listed the environments.

  • 401

    Unauthorized

Example responses
  • {
  "environments": [
    {
      "name": "Dev environment",
      "environment_id": "dev-environment",
      "description": "Dev environment description",
      "tags": "development",
      "color_code": "#FDD13A",
      "created_time": "2021-05-12T23:20:50.52Z",
      "updated_time": "2021-05-12T23:20:50.52Z",
      "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
    }
  ],
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "first": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments?limit=10&offset=0"
  },
  "last": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments?limit=10&offset=0"
  }
}
  • {
  "environments": [
    {
      "name": "Dev environment",
      "environment_id": "dev-environment",
      "description": "Dev environment description",
      "tags": "development",
      "color_code": "#FDD13A",
      "created_time": "2021-05-12T23:20:50.52Z",
      "updated_time": "2021-05-12T23:20:50.52Z",
      "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
    }
  ],
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "first": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments?limit=10&offset=0"
  },
  "last": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments?limit=10&offset=0"
  }
}
  • {
  "message": "Unauthorized"
}
  • {
  "message": "Unauthorized"
}

Create Environment

Create an environment.

Create an environment.

POST /environments
(appConfiguration *AppConfigurationV1) CreateEnvironment(createEnvironmentOptions *CreateEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) CreateEnvironmentWithContext(ctx context.Context, createEnvironmentOptions *CreateEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.environments.create

Auditing

Calling this method generates the following auditing event.

  • apprapp.environments.create

Request

Instantiate the CreateEnvironmentOptions struct and set the fields to provide parameter values for the CreateEnvironment method.

Request Body

Required*
Environment

Request to create Environment

Examples:
View

parameter

WithContext method only

CreateEnvironmentOptions

The CreateEnvironment options.

  • curl --request POST --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments' --header 'Authorization: Bearer {TOKEN}' --header 'Content-Type: application/json' --data '{ "name": <ENVIRONMENT_NAME>, "environment_id": <ENVIRONMENT_ID>, "description": "test", "tags" : "test" }'
  • createEnvironmentOptionsModel := appConfigurationServiceInstance.NewCreateEnvironmentOptions(name, environmentId) 
 createEnvironmentOptionsModel.SetDescription(description) 
 createEnvironmentOptionsModel.SetTags(tags) 
 createEnvironmentOptionsModel.SetColorCode(colorCode) 
 result, response, err := appConfigurationServiceInstance.CreateEnvironment(createEnvironmentOptionsModel)

Response

Response Body

Environment

Details of the environment.

Environment

Details of the environment.

Examples:
View

Status Code

  • 201

    Successfully created the environment.

  • 400

    Bad request. Verify that the information in the request body is complete and correct.

Example responses
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "code": "FTEC1000E",
  "message": "Error while creating the environment."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while creating the environment."
}

Update Environment

Update an environment.

Update an environment.

PUT /environments/{environment_id}
(appConfiguration *AppConfigurationV1) UpdateEnvironment(updateEnvironmentOptions *UpdateEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) UpdateEnvironmentWithContext(ctx context.Context, updateEnvironmentOptions *UpdateEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.environments.update

Auditing

Calling this method generates the following auditing event.

  • apprapp.environments.update

Request

Instantiate the UpdateEnvironmentOptions struct and set the fields to provide parameter values for the UpdateEnvironment method.

Path Parameters

  • environment_id
    Required*
    string

    Environment Id

Request Body

Required*
UpdateEnvironment

Request body to update environment

Examples:
View

parameter

WithContext method only

UpdateEnvironmentOptions

The UpdateEnvironment options.

  • curl --request PUT --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments/{ENVIRONMENT_ID}' --header 'Authorization: Bearer {TOKEN}' --header 'Content-Type: application/json' --data '{ "name": <ENVIRONMENT_NAME>, "description": "test", "tags" : "test" }'
  • updateEnvironmentOptionsModel := appConfigurationServiceInstance.NewUpdateEnvironmentOptions(environmentId) 
 updateEnvironmentOptionsModel.SetName(name) 
 updateEnvironmentOptionsModel.SetDescription(description) 
 updateEnvironmentOptionsModel.SetTags(tags) 
 updateEnvironmentOptionsModel.SetColorCode(colorCode) 
 result, response, err := appConfigurationServiceInstance.UpdateEnvironment(updateEnvironmentOptionsModel)

Response

Response Body

Environment

Details of the environment.

Environment

Details of the environment.

Examples:
View

Status Code

  • 200

    Successfully updated the environment details.

  • 400

    Bad request. Verify that the information in the request body is complete and correct.

  • 404

    Not Found. Verify that the environment id is correct.

Example responses
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "code": "FTEC1007E",
  "message": "Error while updating the environment."
}
  • {
  "code": "FTEC1007E",
  "message": "Error while updating the environment."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while updating the environment. The queried resource 'Environment' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while updating the environment. The queried resource 'Environment' is not available on the server."
}

Get Environment

Retrieve the details of the environment.

Retrieve the details of the environment.

GET /environments/{environment_id}
(appConfiguration *AppConfigurationV1) GetEnvironment(getEnvironmentOptions *GetEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) GetEnvironmentWithContext(ctx context.Context, getEnvironmentOptions *GetEnvironmentOptions) (result *Environment, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.environments.list

Auditing

Calling this method generates the following auditing event.

  • apprapp.environments.read

Request

Instantiate the GetEnvironmentOptions struct and set the fields to provide parameter values for the GetEnvironment method.

Path Parameters

  • environment_id
    Required*
    string

    Environment Id

Query Parameters

  • expand
    boolean

    If set to true, returns expanded view of the resource details.

  • include
    string[]

    Include feature, property, snapshots details in the response.

    Allowable values: [features,properties,snapshots]

parameter

WithContext method only

GetEnvironmentOptions

The GetEnvironment options.

  • curl --request GET --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments/{ENVIRONMENT_ID}?expand=true' --header 'Authorization: Bearer {TOKEN}' 

  • getEnvironmentOptionsModel := appConfigurationServiceInstance.NewGetEnvironmentOptions(environmentId) 
 result, response, err := appConfigurationServiceInstance.GetEnvironment(getEnvironmentOptionsModel)

Response

Response Body

Environment

Details of the environment.

Environment

Details of the environment.

Examples:
View

Status Code

  • 200

    Successfully retrieved the environment details.

  • 404

    Not Found. Verify that the environment id is correct.

Example responses
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "name": "Dev environment",
  "environment_id": "dev-environment",
  "description": "Dev environment description",
  "tags": "development",
  "color_code": "#FDD13A",
  "created_time": "2021-05-12T23:20:50.52Z",
  "updated_time": "2021-05-12T23:20:50.52Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/environments/dev-environment"
}
  • {
  "code": "FTEC1000E",
  "message": "Error while retrieving the environment. The queried resource 'Environment' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while retrieving the environment. The queried resource 'Environment' is not available on the server."
}

Delete Environment

Delete an Environment.

Delete an Environment.

DELETE /environments/{environment_id}
(appConfiguration *AppConfigurationV1) DeleteEnvironment(deleteEnvironmentOptions *DeleteEnvironmentOptions) (response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) DeleteEnvironmentWithContext(ctx context.Context, deleteEnvironmentOptions *DeleteEnvironmentOptions) (response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.environments.delete

Auditing

Calling this method generates the following auditing event.

  • apprapp.environments.delete

Request

Instantiate the DeleteEnvironmentOptions struct and set the fields to provide parameter values for the DeleteEnvironment method.

Path Parameters

  • environment_id
    Required*
    string

    Environment Id

parameter

WithContext method only

DeleteEnvironmentOptions

The DeleteEnvironment options.

  • curl --request DELETE --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments/{ENVIRONMENT_ID}' --header 'Authorization: Bearer {TOKEN}' 

  • deleteEnvironmentOptionsModel := appConfigurationServiceInstance.NewDeleteEnvironmentOptions(environmentId) 
 response, err := appConfigurationServiceInstance.DeleteEnvironment(deleteEnvironmentOptionsModel)

Response

Status Code

  • 204

    Successfully deleted the specified environment.

  • 400

    Bad request. Ensure that at least one environment should exist in the instance.

  • 404

    Not Found. Verify that the environment id is correct.

Example responses
  • {
  "code": "FTEC1008E",
  "message": "Error while deleting the environment."
}
  • {
  "code": "FTEC1008E",
  "message": "Error while deleting the environment."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while deleting the environment. The queried resource 'Environment' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while deleting the environment. The queried resource 'Environment' is not available on the server."
}

Get list of Collections

List of all the collections in the App Configuration service instance.

List of all the collections in the App Configuration service instance.

GET /collections
(appConfiguration *AppConfigurationV1) ListCollections(listCollectionsOptions *ListCollectionsOptions) (result *CollectionList, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) ListCollectionsWithContext(ctx context.Context, listCollectionsOptions *ListCollectionsOptions) (result *CollectionList, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.collections.list

Auditing

Calling this method generates the following auditing event.

  • apprapp.collections.list

Request

Instantiate the ListCollectionsOptions struct and set the fields to provide parameter values for the ListCollections method.

Query Parameters

  • expand
    boolean

    If set to true, returns expanded view of the resource details.

  • sort
    string

    Sort the collection details based on the specified attribute.

    Allowable values: [created_time,updated_time,id,name (default)]

  • tags
    string

    Filter the resources to be returned based on the associated tags. Specify the parameter as a list of comma separated tags. Returns resources associated with any of the specified tags.

    Example: version 1.1, pre-release

  • features
    string[]

    Filter collections by a list of comma separated features.

  • properties
    string[]

    Filter collections by a list of comma separated properties.

  • include
    string[]

    Include feature, property, snapshots details in the response.

    Allowable values: [features,properties,snapshots]

  • limit
    integer

    The number of records to retrieve. By default, the list operation return the first 10 records. To retrieve different set of records, use limit with offset to page through the available records.

    Possible values: 1 ≤ value ≤ 100

    Default: 10

  • offset
    integer

    The number of records to skip. By specifying offset, you retrieve a subset of items that starts with the offset value. Use offset with limit to page through the available records.

    Possible values: value ≥ 0

    Default: 0

  • search
    string

    Searches for the provided keyword and returns the appropriate row with that value. Here the search happens on the '[Name OR Tag]' of the entity

    Example: test tag

parameter

WithContext method only

ListCollectionsOptions

The ListCollections options.

  • curl --request GET --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/collections?expand=true&include=features,properties' --header 'Authorization: Bearer {TOKEN}' 

  • listCollectionsOptionsModel := appConfigurationServiceInstance.NewListCollectionsOptions() 
 listCollectionsOptionsModel.SetExpand(true) 
 result, response, err := appConfigurationServiceInstance.ListCollections(listCollectionsOptionsModel)

Response

Response Body

CollectionList

List of all Collections

CollectionList

List of all Collections.

Examples:
View

Status Code

  • 200

    Successfully listed the collections.

  • 401

    Unauthorized

Example responses
  • {
  "collections": [
    {
      "name": "GHz India Pvt Ltd",
      "collection_id": "ghzindiapvtltd",
      "description": "Collection for GHz Inc",
      "tags": "version: 1.1, pre-release",
      "created_time": "2020-01-09T00:16:07Z",
      "updated_time": "2020-03-09T12:16:07Z",
      "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd",
      "features": [
        {
          "feature_id": "cycle-rentals",
          "name": "Cycle Rentals"
        },
        {
          "feature_id": "discountRate",
          "name": "Discount Rate"
        },
        {
          "feature_id": "longDistanceLimit",
          "name": "Long Distance Limit"
        }
      ],
      "properties": [
        {
          "property_id": "bigbillionday",
          "name": "BigBillionDay"
        },
        {
          "property_id": "newyear",
          "name": "NewYear"
        }
      ],
      "features_count": 3,
      "properties_count": 2
    }
  ],
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "first": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections?limit=10&offset=0"
  },
  "last": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections?limit=10&offset=0"
  }
}
  • {
  "collections": [
    {
      "name": "GHz India Pvt Ltd",
      "collection_id": "ghzindiapvtltd",
      "description": "Collection for GHz Inc",
      "tags": "version: 1.1, pre-release",
      "created_time": "2020-01-09T00:16:07Z",
      "updated_time": "2020-03-09T12:16:07Z",
      "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd",
      "features": [
        {
          "feature_id": "cycle-rentals",
          "name": "Cycle Rentals"
        },
        {
          "feature_id": "discountRate",
          "name": "Discount Rate"
        },
        {
          "feature_id": "longDistanceLimit",
          "name": "Long Distance Limit"
        }
      ],
      "properties": [
        {
          "property_id": "bigbillionday",
          "name": "BigBillionDay"
        },
        {
          "property_id": "newyear",
          "name": "NewYear"
        }
      ],
      "features_count": 3,
      "properties_count": 2
    }
  ],
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "first": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections?limit=10&offset=0"
  },
  "last": {
    "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections?limit=10&offset=0"
  }
}
  • {
  "message": "Unauthorized"
}
  • {
  "message": "Unauthorized"
}

Create Collection

Create a collection.

Create a collection.

POST /collections
(appConfiguration *AppConfigurationV1) CreateCollection(createCollectionOptions *CreateCollectionOptions) (result *CollectionLite, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) CreateCollectionWithContext(ctx context.Context, createCollectionOptions *CreateCollectionOptions) (result *CollectionLite, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.collections.create

Auditing

Calling this method generates the following auditing event.

  • apprapp.collections.create

Request

Instantiate the CreateCollectionOptions struct and set the fields to provide parameter values for the CreateCollection method.

Request Body

Required*
Collection

Request to create Collection

Examples:
View

parameter

WithContext method only

CreateCollectionOptions

The CreateCollection options.

  • curl --request POST --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/collections' --header 'Authorization: Bearer {TOKEN}' --header 'Content-Type: application/json' --data '{"name": <COLLECTION-NAME>,"collection_id": <COLLECTION-ID>,"description": <COLLECTION-DESCRIPTION>,"tags": <COLLECTION-TAGS>}'
  • createCollectionOptionsModel := appConfigurationServiceInstance.NewCreateCollectionOptions(name, collectionId) 
 createCollectionOptionsModel.SetDescription(description) 
 createCollectionOptionsModel.SetTags(tags) 
 result, response, err := appConfigurationServiceInstance.CreateCollection(createCollectionOptionsModel)

Response

Response Body

CollectionLite

Details of the collection.

CollectionLite

Details of the collection.

Examples:
View

Status Code

  • 201

    Successfully created the collection.

  • 400

    Bad request. Verify that the information in the request body is complete and correct.

Example responses
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd"
}
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd"
}
  • {
  "code": "FTEC1003E",
  "message": "Error while creating the collection."
}
  • {
  "code": "FTEC1003E",
  "message": "Error while creating the collection."
}

Update Collection

Update the collection name, tags and description. Collection Id cannot be updated.

Update the collection name, tags and description. Collection Id cannot be updated.

PUT /collections/{collection_id}
(appConfiguration *AppConfigurationV1) UpdateCollection(updateCollectionOptions *UpdateCollectionOptions) (result *CollectionLite, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) UpdateCollectionWithContext(ctx context.Context, updateCollectionOptions *UpdateCollectionOptions) (result *CollectionLite, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.collections.update

Auditing

Calling this method generates the following auditing event.

  • apprapp.collections.update

Request

Instantiate the UpdateCollectionOptions struct and set the fields to provide parameter values for the UpdateCollection method.

Path Parameters

  • collection_id
    Required*
    string

    Collection Id of the collection

Request Body

Required*
UpdateCollection

Request body of the update collection request

Examples:
View

parameter

WithContext method only

UpdateCollectionOptions

The UpdateCollection options.

  • curl --request PUT --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/collections/{COLLECTION_ID}' --header 'Authorization: Bearer {TOKEN}' --header 'Content-Type: application/json' --data '{"name": <COLLECTION-NAME>,"description": <COLLECTION-DESCRIPTION>,"tags": <COLLECTION-TAGS>}'
  • updateCollectionOptionsModel := appConfigurationServiceInstance.NewUpdateCollectionOptions(collectionId) 
 updateCollectionOptionsModel.SetName(name) 
 updateCollectionOptionsModel.SetTags(tags) 
 updateCollectionOptionsModel.SetDescription(description) 
 result, response, err := appConfigurationServiceInstance.UpdateCollection(updateCollectionOptionsModel)

Response

Response Body

CollectionLite

Details of the collection.

CollectionLite

Details of the collection.

Examples:
View

Status Code

  • 200

    Successfully updated the collection details.

  • 400

    Bad request. Verify that the information in the request body is complete and correct.

  • 404

    Not Found. Verify that the collection id is correct.

Example responses
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd"
}
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd"
}
  • {
  "code": "FTEC1007E",
  "message": "Error while updating the collection."
}
  • {
  "code": "FTEC1007E",
  "message": "Error while updating the collection."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while updating the collection. The queried resource 'Collection' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while updating the collection. The queried resource 'Collection' is not available on the server."
}

Get Collection

Retrieve the details of the collection.

Retrieve the details of the collection.

GET /collections/{collection_id}
(appConfiguration *AppConfigurationV1) GetCollection(getCollectionOptions *GetCollectionOptions) (result *Collection, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) GetCollectionWithContext(ctx context.Context, getCollectionOptions *GetCollectionOptions) (result *Collection, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.collections.list

Auditing

Calling this method generates the following auditing event.

  • apprapp.collections.read

Request

Instantiate the GetCollectionOptions struct and set the fields to provide parameter values for the GetCollection method.

Path Parameters

  • collection_id
    Required*
    string

    Collection Id of the collection

Query Parameters

  • expand
    boolean

    If set to true, returns expanded view of the resource details.

  • include
    string[]

    Include feature, property, snapshots details in the response.

    Allowable values: [features,properties,snapshots]

parameter

WithContext method only

GetCollectionOptions

The GetCollection options.

  • curl --request GET --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/collections/{COLLECTION_ID}?expand=true&include=features,properties' --header 'Authorization: Bearer {TOKEN}' 

  • getCollectionOptionsModel := appConfigurationServiceInstance.NewGetCollectionOptions(collectionId) 
 result, response, err := appConfigurationServiceInstance.GetCollection(getCollectionOptionsModel)

Response

Response Body

Collection

Details of the collection.

Collection

Details of the collection.

Examples:
View

Status Code

  • 200

    Successfully retrieved the collection details.

  • 404

    Not Found. Verify that the collection id is correct.

Example responses
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd",
  "features": [
    {
      "feature_id": "cycle-rentals",
      "name": "Cycle Rentals"
    },
    {
      "feature_id": "discountRate",
      "name": "Discount Rate"
    },
    {
      "feature_id": "longDistanceLimit",
      "name": "Long Distance Limit"
    }
  ],
  "properties": [
    {
      "property_id": "bigbillionday",
      "name": "BigBillionDay"
    },
    {
      "property_id": "newyearday",
      "name": "NewYearDay"
    }
  ],
  "features_count": 3,
  "properties_count": 2
}
  • {
  "name": "GHz India Pvt Ltd",
  "collection_id": "ghzindiapvtltd",
  "description": "Collection for GHz Inc",
  "tags": "version: 1.1, pre-release",
  "created_time": "2020-01-09T00:16:07Z",
  "updated_time": "2020-03-09T12:16:07Z",
  "href": "https://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/collections/ghzindiapvtltd",
  "features": [
    {
      "feature_id": "cycle-rentals",
      "name": "Cycle Rentals"
    },
    {
      "feature_id": "discountRate",
      "name": "Discount Rate"
    },
    {
      "feature_id": "longDistanceLimit",
      "name": "Long Distance Limit"
    }
  ],
  "properties": [
    {
      "property_id": "bigbillionday",
      "name": "BigBillionDay"
    },
    {
      "property_id": "newyearday",
      "name": "NewYearDay"
    }
  ],
  "features_count": 3,
  "properties_count": 2
}
  • {
  "code": "FTEC1000E",
  "message": "Error while retrieving the collection. The queried resource 'Collection' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while retrieving the collection. The queried resource 'Collection' is not available on the server."
}

Delete Collection

Delete the collection.

Delete the collection.

DELETE /collections/{collection_id}
(appConfiguration *AppConfigurationV1) DeleteCollection(deleteCollectionOptions *DeleteCollectionOptions) (response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) DeleteCollectionWithContext(ctx context.Context, deleteCollectionOptions *DeleteCollectionOptions) (response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.collections.delete

Auditing

Calling this method generates the following auditing event.

  • apprapp.collections.delete

Request

Instantiate the DeleteCollectionOptions struct and set the fields to provide parameter values for the DeleteCollection method.

Path Parameters

  • collection_id
    Required*
    string

    Collection Id of the collection

parameter

WithContext method only

DeleteCollectionOptions

The DeleteCollection options.

  • curl --request DELETE --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/collections/{COLLECTION_ID}' --header 'Authorization: Bearer {TOKEN}' 

  • deleteCollectionOptionsModel := appConfigurationServiceInstance.NewDeleteCollectionOptions(collectionId) 
 response, err := appConfigurationServiceInstance.DeleteCollection(deleteCollectionOptionsModel)

Response

Status Code

  • 204

    Successfully deleted the specified collection.

  • 404

    Not Found. Verify that the collection id is correct.

Example responses
  • {
  "code": "FTEC1000E",
  "message": "Error while deleting the collection. The queried resource 'Collection' is not available on the server."
}
  • {
  "code": "FTEC1000E",
  "message": "Error while deleting the collection. The queried resource 'Collection' is not available on the server."
}

Get list of Features

List all the feature flags in the specified environment.

List all the feature flags in the specified environment.

GET /environments/{environment_id}/features
(appConfiguration *AppConfigurationV1) ListFeatures(listFeaturesOptions *ListFeaturesOptions) (result *FeaturesList, response *core.DetailedResponse, err error)
(appConfiguration *AppConfigurationV1) ListFeaturesWithContext(ctx context.Context, listFeaturesOptions *ListFeaturesOptions) (result *FeaturesList, response *core.DetailedResponse, err error)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • apprapp.features.list

Auditing

Calling this method generates the following auditing event.

  • apprapp.features.list

Request

Instantiate the ListFeaturesOptions struct and set the fields to provide parameter values for the ListFeatures method.

Path Parameters

  • environment_id
    Required*
    string

    Environment Id

Query Parameters

  • expand
    boolean

    If set to true, returns expanded view of the resource details.

  • sort
    string

    Sort the feature details based on the specified attribute.

    Allowable values: [created_time,updated_time,id,name (default)]

  • tags
    string

    Filter the resources to be returned based on the associated tags. Specify the parameter as a list of comma separated tags. Returns resources associated with any of the specified tags.

    Example: version 1.1, pre-release

  • collections
    string[]

    Filter features by a list of comma separated collections.

  • segments
    string[]

    Filter features by a list of comma separated segments.

  • include
    string[]

    Include the associated collections or targeting rules or change request details in the response.

    Allowable values: [collections,rules,change_request]

  • limit
    integer

    The number of records to retrieve. By default, the list operation return the first 10 records. To retrieve different set of records, use limit with offset to page through the available records.

    Possible values: 1 ≤ value ≤ 100

    Default: 10

  • offset
    integer

    The number of records to skip. By specifying offset, you retrieve a subset of items that starts with the offset value. Use offset with limit to page through the available records.

    Possible values: value ≥ 0

    Default: 0

  • search
    string

    Searches for the provided keyword and returns the appropriate row with that value. Here the search happens on the '[Name OR Tag]' of the entity

    Example: test tag

parameter

WithContext method only

ListFeaturesOptions

The ListFeatures options.

  • curl --request GET --url 'https://{REGION}.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/{GUID}/environments/{ENVIRONMENT_ID}/features' --header 'Authorization: Bearer {TOKEN}' 

  • listFeaturesOptionsModel := appConfigurationServiceInstance.NewListFeaturesOptions(environmentId) 
 result, response, err := appConfigurationServiceInstance.ListFeatures(listFeaturesOptionsModel)

Response

Response Body

FeaturesList

List of all features

FeaturesList

List of all features.

Examples:
View