IBM Cloud API Docs

Introduction

Service brokers manage the lifecycle of services. The IBM Cloud® platform interacts with service brokers to provision and manage instances and service bindings. Instances are an instantiation of an offering. Service bindings are the representation of an association between an application and a service instance, which often contains the credentials that the application uses to communicate with the service instance. Valid metadata values create a successful REST API response when a request is run. For more information, see Developing and hosting your service brokers.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>open-service-broker</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:open-service-broker:{version}'

Replace {version} in these examples with the release version.

View on GitHub

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

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/platform-services-go-sdk/openservicebrokerv1"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/openservicebrokerv1

View on GitHub

OSB 2.12 specification

The IBM Cloud Open Service Broker API is based on the Open Service Broker API (OSB) version 2.12 specification. For more information, see the Open Broker API spec.

Sample brokers

IBM Cloud provides the following public broker samples:https://github.com/IBM/sample-resource-service-brokers.

Broker information provided by the IBM Cloud platform

Your service broker receives the following information from the IBM Cloud platform:

X-Broker-API-Originating-Identity

The user identity header is provided through an API originating identity header. This request header includes the user's IBM Cloud IAM Identity. The IAM Identity is base64 encoded. IBM Cloud supports a single authentication realm: IBMid. The IBMid realm uses an IBMid Unique ID (IUI) to identify the user's identity in IBM Cloud. This IUI is an opaque string to the service provider.

Example:

X-Broker-API-Originating-Identity: ibmcloud eyJpYW1faWQiOiJJQk1pZC01MEdOUjcxN1lFIn0=
Decoded:
{"iam_id":"IBMid-50GNR717YE"}

API header version

The API version header is 2.12 External link icon. For example, X-Broker-Api-Version: 2.12.

resource instance (PUT) body.context and resource instance (PATCH) body.context

PUT /v2/service_instances/:resource_instance_id and PATCH /v2/service_instances/:resource_instance_id receive the following value within body.context: { "platform": "ibmcloud", "account_id": "tracys-account-id", "crn": "resource-instance-crn" }.

If you need to search for instances, you can use the GhoST API to issue the queries to find the instances that you want to update.

Recommendations on using asynchronous vs synchronous operations

The OSB API supports both synchronous and asynchronous modes of operation. If your operations are going to take 10 seconds or less, synchronous responses are recommended. Otherwise, use the asynchronous mode of operation. For more information, see the OSB specification.

Endpoint URLs

The Open Service Broker API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.open-service-broker.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

  • Private endpoint URL for VPC infrastructure: https://private.open-service-broker.cloud.ibm.com
  • Private endpoint URLs for classic infrastructure:
    • Dallas: https://private.us-south.open-service-broker.cloud.ibm.com
    • Washington DC: https://private.us-east.open-service-broker.cloud.ibm.com

Example API request

curl --request POST --header "content-type: application/json" --header "accept: application/json" --header "authorization: Bearer <IAM token>" --data "{\"query\":\"string\"}" --url "https://api.billing.cloud.ibm.com/v1/resources/billing-options

Replace <IAM token> in this example with the value for your particular API call.

Authentication

Authorization to the Open Service Broker 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.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct 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

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

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

To call each method, you 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 OPEN_SERVICE_BROKER_URL=<SERVICE_URL>
export OPEN_SERVICE_BROKER_AUTHTYPE=iam
export OPEN_SERVICE_BROKER_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/openservicebrokerv1"
}
...
serviceClientOptions := &openservicebrokerv1.OpenServiceBrokerV1Options{}
serviceClient, err := openservicebrokerv1.NewOpenServiceBrokerV1UsingExternalConfig(serviceClientOptions)

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 OPEN_SERVICE_BROKER_URL=<SERVICE_URL>
export OPEN_SERVICE_BROKER_AUTHTYPE=iam
export OPEN_SERVICE_BROKER_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.open_service_broker.v1.OpenServiceBroker;
...
OpenServiceBroker serviceClient = OpenServiceBroker.newInstance();

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 OPEN_SERVICE_BROKER_URL=<SERVICE_URL>
export OPEN_SERVICE_BROKER_AUTHTYPE=iam
export OPEN_SERVICE_BROKER_APIKEY=<API_KEY>

Example of constructing the service client

const OpenServiceBrokerV1 = require('@ibm-cloud/platform-services/open-service-broker/v1');
...
const serviceClient = OpenServiceBrokerV1.newInstance({});

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 OPEN_SERVICE_BROKER_URL=<SERVICE_URL>
export OPEN_SERVICE_BROKER_AUTHTYPE=iam
export OPEN_SERVICE_BROKER_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import OpenServiceBrokerV1
...
service_client = OpenServiceBrokerV1.new_instance()

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When an API method is called, an event is generated that you can then track and audit from within Activity Tracker. For methods that generate these events, the specific event type is listed with each individual method. For more information about how to track Account and Billing activity, see Auditing events for account management.

You can also call service brokers by using the IBM Cloud resource controller APIs, and use these APIs to monitor API activity that is related to the service brokers within your account. For more information, see Resource Controller API.

Error handling

The Open Service Broker API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is a failure, and a 500 response is an internal system error.

Additional headers

Some broker services accept special parameters in headers that are passed with the request. These additional headers might be required to make successful requests to the API. You can pass request header parameters in all requests or in a single request to the service. For the OSB API, these parameters include the user identity header and the API version header.

See the following related APIs for managing IBM Cloud resources:

Methods

Create (provision) a service instance

Create a service instance with an ID. When your service broker receives a provision request from the IBM Cloud platform, it must take whatever action is necessary to create a new resource.

When a user creates a service instance from the IBM Cloud console or the IBM Cloud CLI, the IBM Cloud platform validates that the user has permission to create the service instance by using IBM Cloud Identity and access management. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) is invoked.

When provisioning occurs, the IBM Cloud platform provides the following values:

  • The IBM Cloud context is included in the context variable
  • The X-Broker-API-Originating-Identity has the IBM IAM ID of the user that initiated the request
  • The parameters section includes the requested location and extra parameters that are required by your service.

Create a service instance with an ID. When your service broker receives a provision request from the IBM Cloud platform, it must take whatever action is necessary to create a new resource.

When a user creates a service instance from the IBM Cloud console or the IBM Cloud CLI, the IBM Cloud platform validates that the user has permission to create the service instance by using IBM Cloud Identity and access management. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) is invoked.

When provisioning occurs, the IBM Cloud platform provides the following values:

  • The IBM Cloud context is included in the context variable
  • The X-Broker-API-Originating-Identity has the IBM IAM ID of the user that initiated the request
  • The parameters section includes the requested location and extra parameters that are required by your service.

Create a service instance with an ID. When your service broker receives a provision request from the IBM Cloud platform, it must take whatever action is necessary to create a new resource.

When a user creates a service instance from the IBM Cloud console or the IBM Cloud CLI, the IBM Cloud platform validates that the user has permission to create the service instance by using IBM Cloud Identity and access management. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) is invoked.

When provisioning occurs, the IBM Cloud platform provides the following values:

  • The IBM Cloud context is included in the context variable
  • The X-Broker-API-Originating-Identity has the IBM IAM ID of the user that initiated the request
  • The parameters section includes the requested location and extra parameters that are required by your service.

Create a service instance with an ID. When your service broker receives a provision request from the IBM Cloud platform, it must take whatever action is necessary to create a new resource.

When a user creates a service instance from the IBM Cloud console or the IBM Cloud CLI, the IBM Cloud platform validates that the user has permission to create the service instance by using IBM Cloud Identity and access management. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) is invoked.

When provisioning occurs, the IBM Cloud platform provides the following values:

  • The IBM Cloud context is included in the context variable
  • The X-Broker-API-Originating-Identity has the IBM IAM ID of the user that initiated the request
  • The parameters section includes the requested location and extra parameters that are required by your service.

Create a service instance with an ID. When your service broker receives a provision request from the IBM Cloud platform, it must take whatever action is necessary to create a new resource.

When a user creates a service instance from the IBM Cloud console or the IBM Cloud CLI, the IBM Cloud platform validates that the user has permission to create the service instance by using IBM Cloud Identity and access management. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) is invoked.

When provisioning occurs, the IBM Cloud platform provides the following values:

  • The IBM Cloud context is included in the context variable
  • The X-Broker-API-Originating-Identity has the IBM IAM ID of the user that initiated the request
  • The parameters section includes the requested location and extra parameters that are required by your service.
PUT /v2/service_instances/{instance_id}
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceInstance(replaceServiceInstanceOptions *ReplaceServiceInstanceOptions) (result *InstancePutResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceInstanceWithContext(ctx context.Context, replaceServiceInstanceOptions *ReplaceServiceInstanceOptions) (result *InstancePutResp, response *core.DetailedResponse, err error)
replaceServiceInstance(params)
ServiceCall<InstancePutResp> replaceServiceInstance(ReplaceServiceInstanceOptions replaceServiceInstanceOptions)
replace_service_instance(self,
        instance_id: str,
        *,
        context: 'Context' = None,
        plan_id: str = None,
        service_id: str = None,
        organization_guid: str = None,
        parameters: dict = None,
        space_guid: str = None,
        accepts_incomplete: bool = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the ReplaceServiceInstanceOptions struct and set the fields to provide parameter values for the ReplaceServiceInstance method.

Use the ReplaceServiceInstanceOptions.Builder to create a ReplaceServiceInstanceOptions object that contains the parameter values for the replaceServiceInstance method.

Path Parameters

  • The instance_id of a service instance is provided by the IBM Cloud platform. This ID will be used for future requests to bind, update, and deprovision, so the broker can use it to correlate the resource it creates.

Query Parameters

  • A value of true indicates that both the IBM Cloud platform and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can deprovision only a service instance of the requested plan asynchronously, the broker must reject the request with a 422 Unprocessable Entity.

Request body

WithContext method only

The ReplaceServiceInstance options.

parameters

  • The instance_id of a service instance is provided by the IBM Cloud platform. This ID will be used for future requests to bind, update, and deprovision, so the broker can use it to correlate the resource it creates.

  • Platform specific contextual information under which the service instance is to be provisioned.

  • The ID of the plan for which the service instance is requested, which is stored in the catalog.json of your broker. This value should be a GUID and it must be unique to a service.

    Examples:
    value
    _source
    _lines
    _html
  • The ID of the service stored in the catalog.json of your broker. This value should be a GUID and it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • Deprecated in favor of context. The identifier for the project space within the IBM Cloud platform organization. Although most brokers do not use this field, it might be helpful for executing operations on a user's behalf. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • Configuration options for the service instance. An opaque object, controller treats this as a blob. Brokers should ensure that the client has provided valid configuration parameters and values for the operation. If this field is not present in the request message, then the broker must NOT change the parameters of the instance as a result of this request.

  • Deprecated in favor of context. The IBM Cloud platform GUID for the organization under which the service instance is to be provisioned. Although most brokers do not use this field, it might be helpful for executing operations on a user's behalf. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • A value of true indicates that both the IBM Cloud platform and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can deprovision only a service instance of the requested plan asynchronously, the broker must reject the request with a 422 Unprocessable Entity.

The replaceServiceInstance options.

parameters

  • The instance_id of a service instance is provided by the IBM Cloud platform. This ID will be used for future requests to bind, update, and deprovision, so the broker can use it to correlate the resource it creates.

  • Platform specific contextual information under which the service instance is to be provisioned.

  • The ID of the plan for which the service instance is requested, which is stored in the catalog.json of your broker. This value should be a GUID and it must be unique to a service.

    Examples:
    value
    _source
    _lines
    _html
  • The ID of the service stored in the catalog.json of your broker. This value should be a GUID and it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • Deprecated in favor of context. The identifier for the project space within the IBM Cloud platform organization. Although most brokers do not use this field, it might be helpful for executing operations on a user's behalf. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • Configuration options for the service instance. An opaque object, controller treats this as a blob. Brokers should ensure that the client has provided valid configuration parameters and values for the operation. If this field is not present in the request message, then the broker must NOT change the parameters of the instance as a result of this request.

  • Deprecated in favor of context. The IBM Cloud platform GUID for the organization under which the service instance is to be provisioned. Although most brokers do not use this field, it might be helpful for executing operations on a user's behalf. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • A value of true indicates that both the IBM Cloud platform and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can deprovision only a service instance of the requested plan asynchronously, the broker must reject the request with a 422 Unprocessable Entity.

  • PUT /v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Acompose-redis%3Aus-south%3Aa%2F46aa677e-e83f-4d17-a2b6-5b752564477c%3A416d769b-682d-4833-8bd7-5ef8778e5b52?accepts_incomplete=true HTTP/1.1
       Host:  https://broker.compose.cloud.ibm.com
       Authorization: basic dXNlcjpwYXNzd29yZA==
       X-Broker-Api-Version: 2.12
       X-Broker-API-Originating-Identity: ibmcloud aWJtaWQtNDU2MzQ1WA==
       {
         "service_id": "0bc9d744-6f8c-4821-9648-2278bf6925bb",  
         "plan_id": "ecc19311-aba2-49f7-8198-1e450c8460d4", 
         "context": {
           "platform": "ibmcloud",
           "account_id": "003e9bc3993aec710d30a5a719e57a80",
           "crn": "crn:v1:bluemix:public:compose-redis:us-south:a/003e9bc3993aec710d30a5a719e57a80:416d769b-682d-4833-8bd7-5ef8778e5b52",
            "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/003e9bc3993aec710d30a5a719e57a80::resource-group:b4570a825f7f4d57aa54e8e1d9507926"
         },
         "parameters": {
           "location": "us-south",
           "optional-param":"parameter required by your service"
         }
       }
  • contextOpt := &openservicebrokerv1.Context{
      AccountID: &accountId,
      Crn:       &instanceId,
      Platform:  core.StringPtr("ibmcloud"),
    }
    paramsOpt := make(map[string]string, 0)
    paramsOpt["example"] = "property"
    
    options := openServiceBrokerService.NewReplaceServiceInstanceOptions(
      instanceId,
    )
    options = options.SetPlanID(planId)
    options = options.SetServiceID(serviceId)
    options = options.SetOrganizationGuid(orgGuid)
    options = options.SetSpaceGuid(spaceGuid)
    options = options.SetContext(contextOpt)
    options = options.SetParameters(paramsOpt)
    options = options.SetAcceptsIncomplete(true)
    
    result, response, err := openServiceBrokerService.ReplaceServiceInstance(options)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(result, "", "  ")
    fmt.Println(string(b))
  • Context contextReq = new Context.Builder()
          .accountId(accountId)
          .crn(instanceId)
          .platform("ibmcloud")
          .build();
    
      Map<String, String> param = new HashMap<String, String>();
      param.put("example", "property");
    
    ReplaceServiceInstanceOptions replaceServiceInstanceOptions = new ReplaceServiceInstanceOptions.Builder()
      .instanceId(instanceId)
      .planId(planId)
      .serviceId(serviceId)
      .organizationGuid(orgGuid)
      .spaceGuid(spaceGuid)
      .context(contextReq)
      .parameters(param)
      .acceptsIncomplete(true)
      .build();
    
    Response<Resp2079872Root> response = service.replaceServiceInstance(replaceServiceInstanceOptions).execute();
    Resp2079872Root result = response.getResult();
    
    System.out.println(result);
  • const context = {
      account_id: accountId,
      crn: instanceId,
      platform: 'ibmcloud',
    };
    
    const pars = { example: 'property'};
    
    const params = {
      instanceId: instanceId,
      organizationGuid: orgGuid,
      planId: planId,
      serviceId: serviceId,
      spaceGuid: spaceGuid,
      context: context,
      parameters: pars,
      acceptsIncomplete: true,
    };
    
    openServiceBrokerService.replaceServiceInstance(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • context = Context(
      account_id=accountId,
      crn=instanceId,
      platform='ibmcloud'
    )
    pars = {}
    response = open_service_broker_service.replace_service_instance(
      instance_id=instanceId,
      organization_guid=orgGuid,
      plan_id=planId,
      service_id=serviceId,
      space_guid=spaceGuid,
      context=context,
      parameters=pars,
      accepts_incomplete=True
    ).get_result()
    
    print(json.dumps(response, indent=2))

Response

Instance PUT response body

Instance PUT response body.

Instance PUT response body.

Instance PUT response body.

Instance PUT response body.

Status Code

  • OK: must be returned if the service instance exists, is fully provisioned, and the requested parameters are identical to the existing service instance.

  • Created - must be returned if the service instance was provisioned as a result of this request.

  • Accepted - must be returned if the service instance provisioning is in progress. This triggers the IBM Cloud platform to poll the Service Instance last_operation Endpoint for operation status. A re-sent PUT request must return a 202 Accepted, not a 200 OK, if the service instance is not yet fully provisioned.

  • Conflict - must be returned if a service instance with the same ID exists but with different attributes. The expected response body is {}, though the description field can be used to return a user-facing error message.

  • Must be returned if the request could not be processed by the broker. For example, the broker supports only asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true

Example responses
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
    }
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
    }
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
    }
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
    }
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "description": "Your service is being created asynchronously.",
      "operation": "Provision_45"
    }
  • {
      "dashboard_url": "http://www.ibm.com/objectstorage/crn:v1:bluemix:public:cloud-object-storage:global:a%2F4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "description": "Your service is being created asynchronously.",
      "operation": "Provision_45"
    }