IBM Cloud API Docs

Introduction

Last updated: 2021-10-19

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

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

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

View on GitHub

https://github.com/IBM/platform-services-python-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/platform-services-go-sdk/openservicebrokerv1"
)

Go get

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

View on GitHub

https://github.com/IBM/platform-services-go-sdk

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.

Related APIs

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

  • instance_id
    Required*
    string

    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

  • accepts_incomplete
    boolean

    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

InstancePutReq

Request body

parameter

WithContext method only

ReplaceServiceInstanceOptions

The ReplaceServiceInstance options.

parameters

  • instanceId
    Required*
    string

    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.

  • context

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

  • planId
    string

    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
  • serviceId
    string

    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
  • organizationGuid
    string

    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
  • parameters
    JsonObject

    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.

  • spaceGuid
    string

    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
  • acceptsIncomplete
    boolean

    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.

ReplaceServiceInstanceOptions

The replaceServiceInstance options.

parameters

  • instance_id
    Required*
    str

    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.

  • context

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

  • plan_id
    str

    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
  • service_id
    str

    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
  • organization_guid
    str

    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
  • parameters
    dict

    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.

  • space_guid
    str

    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
  • accepts_incomplete
    bool

    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

Response Body

InstancePutResp

Instance PUT response body

InstancePutResp

Instance PUT response body.

InstancePutResp

Instance PUT response body.

InstancePutResp

Instance PUT response body.

InstancePutResp

Instance PUT response body.

Status Code

  • 200

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

  • 201

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

  • 202

    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.

  • 409

    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.

  • 422

    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"
}
  • {}
  • {}
  • {
  "error": "AsyncRequired",
  "description": "This service plan requires support for asynchronous service operations."
}
  • {
  "error": "AsyncRequired",
  "description": "This service plan requires support for asynchronous service operations."
}

Update a service instance

Patch a service instance by CRN. Enabling this endpoint allows your user to change plans and service parameters in a provisioned service instance. If your offering supports multiple plans, and you want users to be able to change plans for a provisioned instance, you must enable the ability for users to update their service instance.

To enable support for the update of the plan, a broker must declare support per service by specifying "plan_updateable": true in your brokers' catalog.json.

Patch a service instance by CRN. Enabling this endpoint allows your user to change plans and service parameters in a provisioned service instance. If your offering supports multiple plans, and you want users to be able to change plans for a provisioned instance, you must enable the ability for users to update their service instance.

To enable support for the update of the plan, a broker must declare support per service by specifying "plan_updateable": true in your brokers' catalog.json.

Patch a service instance by CRN. Enabling this endpoint allows your user to change plans and service parameters in a provisioned service instance. If your offering supports multiple plans, and you want users to be able to change plans for a provisioned instance, you must enable the ability for users to update their service instance.

To enable support for the update of the plan, a broker must declare support per service by specifying "plan_updateable": true in your brokers' catalog.json.

Patch a service instance by CRN. Enabling this endpoint allows your user to change plans and service parameters in a provisioned service instance. If your offering supports multiple plans, and you want users to be able to change plans for a provisioned instance, you must enable the ability for users to update their service instance.

To enable support for the update of the plan, a broker must declare support per service by specifying "plan_updateable": true in your brokers' catalog.json.

Patch a service instance by CRN. Enabling this endpoint allows your user to change plans and service parameters in a provisioned service instance. If your offering supports multiple plans, and you want users to be able to change plans for a provisioned instance, you must enable the ability for users to update their service instance.

To enable support for the update of the plan, a broker must declare support per service by specifying "plan_updateable": true in your brokers' catalog.json.

PATCH /v2/service_instances/{instance_id}
(openServiceBroker *OpenServiceBrokerV1) UpdateServiceInstance(updateServiceInstanceOptions *UpdateServiceInstanceOptions) (result *InstancePatchResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) UpdateServiceInstanceWithContext(ctx context.Context, updateServiceInstanceOptions *UpdateServiceInstanceOptions) (result *InstancePatchResp, response *core.DetailedResponse, err error)
updateServiceInstance(params)
ServiceCall<InstancePatchResp> updateServiceInstance(UpdateServiceInstanceOptions updateServiceInstanceOptions)
update_service_instance(self,
        instance_id: str,
        *,
        service_id: str = None,
        context: 'Context' = None,
        parameters: dict = None,
        plan_id: str = None,
        previous_values: dict = None,
        accepts_incomplete: bool = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the UpdateServiceInstanceOptions struct and set the fields to provide parameter values for the UpdateServiceInstance method.

Use the UpdateServiceInstanceOptions.Builder to create a UpdateServiceInstanceOptions object that contains the parameter values for the updateServiceInstance method.

Path Parameters

  • instance_id
    Required*
    string

    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

  • accepts_incomplete
    boolean

    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

InstancePatchReq

Request body

parameter

WithContext method only

UpdateServiceInstanceOptions

The UpdateServiceInstance options.

parameters

  • instanceId
    Required*
    string

    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.

  • serviceId
    string

    The ID of the service stored in the catalog.json of your broker. This value should be a GUID. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • context

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

  • parameters
    JsonObject

    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.

  • planId
    string

    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. Must be unique to a service. If present, must be a non-empty string. If this field is not present in the request message, then the broker must NOT change the plan of the instance as a result of this request.

    Examples:
    value
    _source
    _lines
    _html
  • previousValues
    JsonObject

    Information about the service instance before the update.

  • acceptsIncomplete
    boolean

    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.

UpdateServiceInstanceOptions

The updateServiceInstance options.

parameters

  • instance_id
    Required*
    str

    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.

  • service_id
    str

    The ID of the service stored in the catalog.json of your broker. This value should be a GUID. It must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • context

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

  • parameters
    dict

    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.

  • plan_id
    str

    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. Must be unique to a service. If present, must be a non-empty string. If this field is not present in the request message, then the broker must NOT change the plan of the instance as a result of this request.

    Examples:
    value
    _source
    _lines
    _html
  • previous_values
    dict

    Information about the service instance before the update.

  • accepts_incomplete
    bool

    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.

  •  curl -X PATCH -H "Accept:application/json" -H "Content-Type:application/json" -H "X-Broker-Api-Version:2.12" -H "X-Broker-Api-Originating-Identity:ibmcloud eyJpYW1faWQiOiJJQk1pZC0zMTAwMDJNNEpGIiwic3ViIjoiYmx1ZW1peF91aV9zb3Rlc3RAbWFpbGluYXRvci5jb20ifQ==" -u "TestServiceBrokerUser:TestServiceBrokerPassword" -d "{"context":{"account_id":"499b176abb3e1c9727df87ae48b27c7b","crn":"crn:v1:bluemix:public:testjavaresourceservicebrokername:us-south:a/499b176abb3e1c9727df87ae48b27c7b:7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7::","platform":"ibmcloud","resource_group_crn":"crn:v1:bluemix:public:resource-controller::a/499b176abb3e1c9727df87ae48b27c7b::resource-group:2a5f74056b254efbaab5e9e28a7111414","target_crn":"crn:v1:bluemix:public:resource-catalog::a/e97a8c01ac694e308ef3ad7795c7cdb3::deployment:e62e2c19-0c3b-41e3-b8b3-c71762ecd489%3Aus-south38399"}, "parameters":{"parameter1":1, "parameter2":"value"}, "plan_id":"e1031579-4b42-4169-b7cf-f7793c616fdc", "previous_values":{"plan_id":"e62e2c19-0c3b-41e3-b8b3-c71762ecd489", "service_id":"cb55391b-3416-4943-a6a6-a541778c1924"}, "service_id":"cb55391b-3416-4943-a6a6-a541778c1924"}" http://localhost:3000/v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3A%3A?accepts_incomplete=true 
  • contextOpt := &openservicebrokerv1.Context{
  AccountID: &accountId,
  Crn:       &instanceId,
  Platform:  core.StringPtr("ibmcloud"),
}

paramsOpt := make(map[string]string, 0)
paramsOpt["example"] = "property"

previousValues := make(map[string]string, 0)
previousValues["plan_id"] = planId

options := openServiceBrokerService.NewUpdateServiceInstanceOptions(
  instanceId,
)
options = options.SetPlanID(planId)
options = options.SetServiceID(serviceId)
options = options.SetContext(contextOpt)
options = options.SetParameters(paramsOpt)
options = options.SetAcceptsIncomplete(true)

result, response, err := openServiceBrokerService.UpdateServiceInstance(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");

Map<String, String> previousValues = new HashMap<String, String>();
previousValues.put("plan_id", planId);

UpdateServiceInstanceOptions updateServiceInstanceOptions = new UpdateServiceInstanceOptions.Builder()
  .instanceId(instanceId)
  .planId(planId)
  .serviceId(serviceId)
  .context(contextReq)
  .parameters(param)
  .previousValues(previousValues)
  .acceptsIncomplete(true)
  .build();

Response<Resp2079874Root> response = service.updateServiceInstance(updateServiceInstanceOptions).execute();
Resp2079874Root result = response.getResult();

System.out.println(result);
  • const context = {
  account_id: accountId,
  crn: instanceId,
  platform: 'ibmcloud',
};

const pars = { example: 'property'};
const prevValues = { previous: 'values'};

const params = {
  instanceId: instanceId,
  planId: planId,
  serviceId: serviceId,
  context: context,
  parameters: pars,
  previousValues: prevValues,
  acceptsIncomplete: true,
};

openServiceBrokerService.updateServiceInstance(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 = {}
prevValues = {}
response = open_service_broker_service.update_service_instance(
  instance_id=instanceId,
  plan_id=planId,
  service_id=serviceId,
  context=context,
  parameters=pars,
  previous_values=prevValues,
  accepts_incomplete=True
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

InstancePatchResp

Instance PATCH response body

InstancePatchResp

Instance PATCH response body.

InstancePatchResp

Instance PATCH response body.

InstancePatchResp

Instance PATCH response body.

InstancePatchResp

Instance PATCH response body.

Status Code

  • 200

    OK - must be returned if the request's changes are applied. The expected response body is {}.

  • 202

    Accepted - must be returned if the service instance update is in progress. This triggers the platform marketplace to poll the Last Operation for operation status. Note that a re-sent PATCH request must return a 202 Accepted, not a 200 OK, if the requested update has not yet completed.

  • 422

    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
  • {}
  • {}
  • {
  "operation": "task_10"
}
  • {
  "operation": "task_10"
}
  • {
  "error": "AsyncRequired",
  "description": "This service plan requires support for asynchronous service operations."
}
  • {
  "error": "AsyncRequired",
  "description": "This service plan requires support for asynchronous service operations."
}

Delete (deprovision) a service instance

Delete (deprovision) a service instance by CRN. When a service broker receives a deprovision request from the IBM Cloud platform, it must delete any resources that it created during the provision. Usually this means that all resources are immediately reclaimed for future provisions.

Delete (deprovision) a service instance by CRN. When a service broker receives a deprovision request from the IBM Cloud platform, it must delete any resources that it created during the provision. Usually this means that all resources are immediately reclaimed for future provisions.

Delete (deprovision) a service instance by CRN. When a service broker receives a deprovision request from the IBM Cloud platform, it must delete any resources that it created during the provision. Usually this means that all resources are immediately reclaimed for future provisions.

Delete (deprovision) a service instance by CRN. When a service broker receives a deprovision request from the IBM Cloud platform, it must delete any resources that it created during the provision. Usually this means that all resources are immediately reclaimed for future provisions.

Delete (deprovision) a service instance by CRN. When a service broker receives a deprovision request from the IBM Cloud platform, it must delete any resources that it created during the provision. Usually this means that all resources are immediately reclaimed for future provisions.

DELETE /v2/service_instances/{instance_id}
(openServiceBroker *OpenServiceBrokerV1) DeleteServiceInstance(deleteServiceInstanceOptions *DeleteServiceInstanceOptions) (response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) DeleteServiceInstanceWithContext(ctx context.Context, deleteServiceInstanceOptions *DeleteServiceInstanceOptions) (response *core.DetailedResponse, err error)
deleteServiceInstance(params)
ServiceCall<Void> deleteServiceInstance(DeleteServiceInstanceOptions deleteServiceInstanceOptions)
delete_service_instance(self,
        instance_id: str,
        service_id: str,
        plan_id: str,
        *,
        accepts_incomplete: bool = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the DeleteServiceInstanceOptions struct and set the fields to provide parameter values for the DeleteServiceInstance method.

Use the DeleteServiceInstanceOptions.Builder to create a DeleteServiceInstanceOptions object that contains the parameter values for the deleteServiceInstance method.

Path Parameters

  • instance_id
    Required*
    string

    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

  • service_id
    Required*
    string

    The ID of the service stored in the catalog.json of your broker. This value should be a GUID. Must be a non-empty string.

  • plan_id
    Required*
    string

    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. must be a non-empty string.

  • accepts_incomplete
    boolean

    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.

parameter

WithContext method only

DeleteServiceInstanceOptions

The DeleteServiceInstance options.

parameters

  • instanceId
    Required*
    string

    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.

  • serviceId
    Required*
    string

    The ID of the service stored in the catalog.json of your broker. This value should be a GUID. Must be a non-empty string.

  • planId
    Required*
    string

    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. must be a non-empty string.

  • acceptsIncomplete
    boolean

    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.

DeleteServiceInstanceOptions

The deleteServiceInstance options.

parameters

  • instance_id
    Required*
    str

    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.

  • service_id
    Required*
    str

    The ID of the service stored in the catalog.json of your broker. This value should be a GUID. Must be a non-empty string.

  • plan_id
    Required*
    str

    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. must be a non-empty string.

  • accepts_incomplete
    bool

    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.

  •  curl -X DELETE -H "Accept:application/json" -H "X-Broker-Api-Version:2.12" -H "X-Broker-Api-Originating-Identity:ibmcloud eyJpYW1faWQiOiJJQk1pZC0zMTAwMDJNNEpGIiwic3ViIjoiYmx1ZW1peF91aV9zb3Rlc3RAbWFpbGluYXRvci5jb20ifQ==" -u "TestServiceBrokerUser:TestServiceBrokerPassword" "http://localhost:3000/v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3A%3A?accepts_incomplete=true&plan_id=e62e2c19-0c3b-41e3-b8b3-c71762ecd489&service_id=cb55391b-3416-4943-a6a6-a541778c1924"
  • options := openServiceBrokerService.NewDeleteServiceInstanceOptions(
  serviceId,
  planId,
  instanceId,
)

result, response, err := openServiceBrokerService.DeleteServiceInstance(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • DeleteServiceInstanceOptions deleteServiceInstanceOptions = new DeleteServiceInstanceOptions.Builder()
  .serviceId(serviceId)
  .planId(planId)
  .instanceId(instanceId)
  .acceptsIncomplete(true)
  .build();

Response<Resp2079874Root> response = service.deleteServiceInstance(deleteServiceInstanceOptions).execute();
Resp2079874Root result = response.getResult();

System.out.println(result);
  • const params = {
  serviceId: serviceId,
  planId: planId,
  instanceId: instanceId,
};

openServiceBrokerService.deleteServiceInstance(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.delete_service_instance(
  instance_id=instanceId,
  plan_id=planId,
  service_id=serviceId,
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

object

Status Code

  • 200

    OK - must be returned if the service instance was deleted as a result of this request. The expected response body is {}.

  • 202

    Accepted - must be returned if the service instance deletion is in progress. This triggers the marketplace to poll the Service Instance Last Operation Endpoint for operation status. Note that a re-sent DELETE request must return a 202 Accepted, not a 200 OK, if the delete request has not completed yet.

  • 410

    Gone - must be returned if the service instance does not exist. The expected response body is {}.

  • 422

    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
  • {}
  • {}
  • {
  "operation": "task_10"
}
  • {
  "operation": "task_10"
}
  • {}
  • {}

Get the current state of the service instance

Get the current state information associated with the service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service (without deleting it), and when the account is settled enable the service.

This endpoint allows both the provider and IBM Cloud to query for the state of a provisioned service instance. For example, IBM Cloud might query the provider to figure out if a given service is disabled or not and present that state to the user.

Get the current state information associated with the service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service (without deleting it), and when the account is settled enable the service.

This endpoint allows both the provider and IBM Cloud to query for the state of a provisioned service instance. For example, IBM Cloud might query the provider to figure out if a given service is disabled or not and present that state to the user.

Get the current state information associated with the service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service (without deleting it), and when the account is settled enable the service.

This endpoint allows both the provider and IBM Cloud to query for the state of a provisioned service instance. For example, IBM Cloud might query the provider to figure out if a given service is disabled or not and present that state to the user.

Get the current state information associated with the service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service (without deleting it), and when the account is settled enable the service.

This endpoint allows both the provider and IBM Cloud to query for the state of a provisioned service instance. For example, IBM Cloud might query the provider to figure out if a given service is disabled or not and present that state to the user.

Get the current state information associated with the service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service (without deleting it), and when the account is settled enable the service.

This endpoint allows both the provider and IBM Cloud to query for the state of a provisioned service instance. For example, IBM Cloud might query the provider to figure out if a given service is disabled or not and present that state to the user.

GET /bluemix_v1/service_instances/{instance_id}
(openServiceBroker *OpenServiceBrokerV1) GetServiceInstanceState(getServiceInstanceStateOptions *GetServiceInstanceStateOptions) (result *InstanceStateResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) GetServiceInstanceStateWithContext(ctx context.Context, getServiceInstanceStateOptions *GetServiceInstanceStateOptions) (result *InstanceStateResp, response *core.DetailedResponse, err error)
getServiceInstanceState(params)
ServiceCall<InstanceStateResp> getServiceInstanceState(GetServiceInstanceStateOptions getServiceInstanceStateOptions)
get_service_instance_state(self,
        instance_id: str,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetServiceInstanceStateOptions struct and set the fields to provide parameter values for the GetServiceInstanceState method.

Use the GetServiceInstanceStateOptions.Builder to create a GetServiceInstanceStateOptions object that contains the parameter values for the getServiceInstanceState method.

Path Parameters

  • instance_id
    Required*
    string

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

parameter

WithContext method only

GetServiceInstanceStateOptions

The GetServiceInstanceState options.

parameters

  • instanceId
    Required*
    string

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

GetServiceInstanceStateOptions

The getServiceInstanceState options.

parameters

  • instance_id
    Required*
    str

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

  • curl --request GET   --url 'https:///$(broker.host)/bluemix_v1/service_instances/%7Binstance_id%7D'   --header 'authorization: Basic REPLACE_BASIC_AUTH'   --header 'content-type: application/json'
  • options := openServiceBrokerService.NewGetServiceInstanceStateOptions(
  instanceId,
)

result, response, err := openServiceBrokerService.GetServiceInstanceState(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • GetServiceInstanceStateOptions getServiceInstanceStateOptions = new GetServiceInstanceStateOptions.Builder()
  .instanceId(instanceId)
  .build();

Response<Resp1874644Root> response = service.getServiceInstanceState(getServiceInstanceStateOptions).execute();
Resp1874644Root result = response.getResult();

System.out.println(result);
  • const params = {
  instanceId: instanceId,
};

openServiceBrokerService.getServiceInstanceState(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.get_service_instance_state(
  instance_id=instanceId
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

InstanceStateResp

Instance State response body

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

Status Code

  • 200

    OK

Example responses
  • {
  "active": true,
  "enabled": true,
  "last_active": 1656523962
}
  • {
  "active": true,
  "enabled": true,
  "last_active": 1656523962
}

Update the state of a provisioned service instance

Update the state of a provisioned service instance. By updating the service instance, you are either enabling or disabling it. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service without deleting it, and when the account is settled enable the service.

This endpoint allows the provider to enable or disable the state of a provisioned service instance. It is the service provider's responsibility to disable access to the service instance when the disable endpoint is invoked and to re-enable that access when the enable endpoint is invoked.

When your service broker receives an enable or disable request, it should take whatever action is necessary to enable or disable the service. Additionally, if there is a bind request for a disabled service, the broker should reject that request with any code other than 204, and provide a user-facing message in the description.

Update the state of a provisioned service instance. By updating the service instance, you are either enabling or disabling it. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service without deleting it, and when the account is settled enable the service.

This endpoint allows the provider to enable or disable the state of a provisioned service instance. It is the service provider's responsibility to disable access to the service instance when the disable endpoint is invoked and to re-enable that access when the enable endpoint is invoked.

When your service broker receives an enable or disable request, it should take whatever action is necessary to enable or disable the service. Additionally, if there is a bind request for a disabled service, the broker should reject that request with any code other than 204, and provide a user-facing message in the description.

Update the state of a provisioned service instance. By updating the service instance, you are either enabling or disabling it. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service without deleting it, and when the account is settled enable the service.

This endpoint allows the provider to enable or disable the state of a provisioned service instance. It is the service provider's responsibility to disable access to the service instance when the disable endpoint is invoked and to re-enable that access when the enable endpoint is invoked.

When your service broker receives an enable or disable request, it should take whatever action is necessary to enable or disable the service. Additionally, if there is a bind request for a disabled service, the broker should reject that request with any code other than 204, and provide a user-facing message in the description.

Update the state of a provisioned service instance. By updating the service instance, you are either enabling or disabling it. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service without deleting it, and when the account is settled enable the service.

This endpoint allows the provider to enable or disable the state of a provisioned service instance. It is the service provider's responsibility to disable access to the service instance when the disable endpoint is invoked and to re-enable that access when the enable endpoint is invoked.

When your service broker receives an enable or disable request, it should take whatever action is necessary to enable or disable the service. Additionally, if there is a bind request for a disabled service, the broker should reject that request with any code other than 204, and provide a user-facing message in the description.

Update the state of a provisioned service instance. By updating the service instance, you are either enabling or disabling it. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you might need to disable the service without deleting it, and when the account is settled enable the service.

This endpoint allows the provider to enable or disable the state of a provisioned service instance. It is the service provider's responsibility to disable access to the service instance when the disable endpoint is invoked and to re-enable that access when the enable endpoint is invoked.

When your service broker receives an enable or disable request, it should take whatever action is necessary to enable or disable the service. Additionally, if there is a bind request for a disabled service, the broker should reject that request with any code other than 204, and provide a user-facing message in the description.

PUT /bluemix_v1/service_instances/{instance_id}
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceInstanceState(replaceServiceInstanceStateOptions *ReplaceServiceInstanceStateOptions) (result *InstanceStateResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceInstanceStateWithContext(ctx context.Context, replaceServiceInstanceStateOptions *ReplaceServiceInstanceStateOptions) (result *InstanceStateResp, response *core.DetailedResponse, err error)
replaceServiceInstanceState(params)
ServiceCall<InstanceStateResp> replaceServiceInstanceState(ReplaceServiceInstanceStateOptions replaceServiceInstanceStateOptions)
replace_service_instance_state(self,
        instance_id: str,
        *,
        enabled: bool = None,
        initiator_id: str = None,
        reason_code: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the ReplaceServiceInstanceStateOptions struct and set the fields to provide parameter values for the ReplaceServiceInstanceState method.

Use the ReplaceServiceInstanceStateOptions.Builder to create a ReplaceServiceInstanceStateOptions object that contains the parameter values for the replaceServiceInstanceState method.

Path Parameters

  • instance_id
    Required*
    string

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

Request Body

InstanceStatePutReq

Instance State PUT request body

parameter

WithContext method only

ReplaceServiceInstanceStateOptions

The ReplaceServiceInstanceState options.

parameters

  • instanceId
    Required*
    string

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

  • enabled
    boolean

    Indicates the current state of the service instance.

    Examples:
    value
    _source
    _lines
    _html
  • initiatorId
    string

    The IAM ID of the user that initiated the call.

    Examples:
    value
    _source
    _lines
    _html
  • reasonCode
    string

    The reason code for the service instance state change. Valid values are IBMCLOUD_ACCT_ACTIVATE, IBMCLOUD_RECLAMATION_RESTORE, or IBMCLOUD_SERVICE_INSTANCE_BELOW_CAP for enable calls; IBMCLOUD_ACCT_SUSPEND, IBMCLOUD_RECLAMATION_SCHEDULE, or IBMCLOUD_SERVICE_INSTANCE_ABOVE_CAP for disable calls; and IBMCLOUD_ADMIN_REQUEST for enable and disable calls.

    Previously accepted values had a BMX_ prefix, such as BMX_ACCT_ACTIVATE. These values are deprecated.

    Allowable values: [IBMCLOUD_ACCT_ACTIVATE,IBMCLOUD_RECLAMATION_RESTORE,IBMCLOUD_SERVICE_INSTANCE_BELOW_CAP,IBMCLOUD_ACCT_SUSPEND,IBMCLOUD_RECLAMATION_SCHEDULE,IBMCLOUD_SERVICE_INSTANCE_ABOVE_CAP,IBMCLOUD_ADMIN_REQUEST,IBMCLOUD_SERVICE_ADMIN,IBMCLOUD_ADMIN_AUP_REQUEST,IBMCLOUD_SERVICE_SUSPEND,IBMCLOUD_SERVICE_ACTIVATE]

    Examples:
    value
    _source
    _lines
    _html

ReplaceServiceInstanceStateOptions

The replaceServiceInstanceState options.

parameters

  • instance_id
    Required*
    str

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

  • enabled
    bool

    Indicates the current state of the service instance.

    Examples:
    value
    _source
    _lines
    _html
  • initiator_id
    str

    The IAM ID of the user that initiated the call.

    Examples:
    value
    _source
    _lines
    _html
  • reason_code
    str

    The reason code for the service instance state change. Valid values are IBMCLOUD_ACCT_ACTIVATE, IBMCLOUD_RECLAMATION_RESTORE, or IBMCLOUD_SERVICE_INSTANCE_BELOW_CAP for enable calls; IBMCLOUD_ACCT_SUSPEND, IBMCLOUD_RECLAMATION_SCHEDULE, or IBMCLOUD_SERVICE_INSTANCE_ABOVE_CAP for disable calls; and IBMCLOUD_ADMIN_REQUEST for enable and disable calls.

    Previously accepted values had a BMX_ prefix, such as BMX_ACCT_ACTIVATE. These values are deprecated.

    Allowable values: [IBMCLOUD_ACCT_ACTIVATE,IBMCLOUD_RECLAMATION_RESTORE,IBMCLOUD_SERVICE_INSTANCE_BELOW_CAP,IBMCLOUD_ACCT_SUSPEND,IBMCLOUD_RECLAMATION_SCHEDULE,IBMCLOUD_SERVICE_INSTANCE_ABOVE_CAP,IBMCLOUD_ADMIN_REQUEST,IBMCLOUD_SERVICE_ADMIN,IBMCLOUD_ADMIN_AUP_REQUEST,IBMCLOUD_SERVICE_SUSPEND,IBMCLOUD_SERVICE_ACTIVATE]

    Examples:
    value
    _source
    _lines
    _html
  • curl --request PUT   --url 'https:///$(broker.host)/bluemix_v1/service_instances/%7Binstance_id%7D'   --header 'authorization: Basic REPLACE_BASIC_AUTH'   --header 'content-type: application/json'  --data '{"enabled":true,"initiator_id":"IBMid-5500093BHN","reason_code":"IBMCLOUD_RECLAMATION_SCHEDULE"}'
  • options := openServiceBrokerService.NewReplaceServiceInstanceStateOptions(
  instanceId,
)
options = options.SetEnabled(false)
options = options.SetInitiatorID(initiatorId)

result, response, err := openServiceBrokerService.ReplaceServiceInstanceState(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • ReplaceServiceInstanceStateOptions replaceServiceInstanceStateOptions = new ReplaceServiceInstanceStateOptions.Builder()
  .instanceId(instanceId)
  .enabled(false)
  .initiatorId(initiatorId)
  .reasonCode(reasonCode)
  .build();

Response<Resp2448145Root> response = service.replaceServiceInstanceState(replaceServiceInstanceStateOptions).execute();
Resp2448145Root result = response.getResult();

System.out.println(result);
  • const params = {
  instanceId: instanceId,
  enabled: false,
  initiatorId: initiatorId,
  reasonCode: reasonCode,
};

openServiceBrokerService.replaceServiceInstanceState(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.replace_service_instance_state(
  instance_id=instanceId,
  enabled=False,
  initiator_id=initiatorId,
  reason_code=reasonCode
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

InstanceStateResp

Instance State response body

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

InstanceStateResp

Instance State response body.

Status Code

  • 200

    OK

  • 410

    Gone - must be returned if the instance does not exist. The expected response body is {}.

Example responses
  • {
  "active": true,
  "enabled": true,
  "last_active": 1656523962
}
  • {
  "active": true,
  "enabled": true,
  "last_active": 1656523962
}
  • {}
  • {}

Get the status of an `in progress` operation for a service instance

Get last_operation for instance by CRN (for asynchronous provision calls). When a broker returns status code 202 Accepted during a provision, update, or deprovision call, the IBM Cloud platform begins polling the last_operation endpoint to obtain the state of the last requested operation. The broker response must contain the field state and can contain the field description.

Valid values for state are in progress, succeeded, and failed. The platform polls the last_operation endpoint when the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" causes the platform to cease polling. The value that is provided for description is passed through to the platform API client and can be used to provide more detail for users about the progress of the operation.

Get last_operation for instance by CRN (for asynchronous provision calls). When a broker returns status code 202 Accepted during a provision, update, or deprovision call, the IBM Cloud platform begins polling the last_operation endpoint to obtain the state of the last requested operation. The broker response must contain the field state and can contain the field description.

Valid values for state are in progress, succeeded, and failed. The platform polls the last_operation endpoint when the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" causes the platform to cease polling. The value that is provided for description is passed through to the platform API client and can be used to provide more detail for users about the progress of the operation.

Get last_operation for instance by CRN (for asynchronous provision calls). When a broker returns status code 202 Accepted during a provision, update, or deprovision call, the IBM Cloud platform begins polling the last_operation endpoint to obtain the state of the last requested operation. The broker response must contain the field state and can contain the field description.

Valid values for state are in progress, succeeded, and failed. The platform polls the last_operation endpoint when the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" causes the platform to cease polling. The value that is provided for description is passed through to the platform API client and can be used to provide more detail for users about the progress of the operation.

Get last_operation for instance by CRN (for asynchronous provision calls). When a broker returns status code 202 Accepted during a provision, update, or deprovision call, the IBM Cloud platform begins polling the last_operation endpoint to obtain the state of the last requested operation. The broker response must contain the field state and can contain the field description.

Valid values for state are in progress, succeeded, and failed. The platform polls the last_operation endpoint when the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" causes the platform to cease polling. The value that is provided for description is passed through to the platform API client and can be used to provide more detail for users about the progress of the operation.

Get last_operation for instance by CRN (for asynchronous provision calls). When a broker returns status code 202 Accepted during a provision, update, or deprovision call, the IBM Cloud platform begins polling the last_operation endpoint to obtain the state of the last requested operation. The broker response must contain the field state and can contain the field description.

Valid values for state are in progress, succeeded, and failed. The platform polls the last_operation endpoint when the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" causes the platform to cease polling. The value that is provided for description is passed through to the platform API client and can be used to provide more detail for users about the progress of the operation.

GET /v2/service_instances/{instance_id}/last_operation
(openServiceBroker *OpenServiceBrokerV1) GetLastOperation(getLastOperationOptions *GetLastOperationOptions) (result *InstanceLastOperationResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) GetLastOperationWithContext(ctx context.Context, getLastOperationOptions *GetLastOperationOptions) (result *InstanceLastOperationResp, response *core.DetailedResponse, err error)
getLastOperation(params)
ServiceCall<InstanceLastOperationResp> getLastOperation(GetLastOperationOptions getLastOperationOptions)
get_last_operation(self,
        instance_id: str,
        *,
        operation: str = None,
        plan_id: str = None,
        service_id: str = None,
        last_poll_time: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetLastOperationOptions struct and set the fields to provide parameter values for the GetLastOperation method.

Use the GetLastOperationOptions.Builder to create a GetLastOperationOptions object that contains the parameter values for the getLastOperation method.

Path Parameters

  • instance_id
    Required*
    string

    The unique instance ID generated during provisioning by the IBM Cloud platform.

Query Parameters

  • operation
    string

    A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for provision and update, and deprovision requests, the IBM Cloud platform provides the same value by using this query parameter as a URL-encoded string. If present, must be a non-empty string.

  • plan_id
    string

    ID of the plan from the catalog.json in your broker. If present, must be a non-empty string

  • service_id
    string

    ID of the service from the catalog.json in your service broker. If present, must be a non-empty string

  • last_poll_time
    string

    Time in seconds since epoch when the IBM Cloud platform will stop polling. This value will change for subsequent last_operation calls if the poll_after is specified in response to current last_operation call.

parameter

WithContext method only

GetLastOperationOptions

The GetLastOperation options.

parameters

  • instanceId
    Required*
    string

    The unique instance ID generated during provisioning by the IBM Cloud platform.

  • operation
    string

    A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for provision and update, and deprovision requests, the IBM Cloud platform provides the same value by using this query parameter as a URL-encoded string. If present, must be a non-empty string.

  • planId
    string

    ID of the plan from the catalog.json in your broker. If present, must be a non-empty string.

  • serviceId
    string

    ID of the service from the catalog.json in your service broker. If present, must be a non-empty string.

  • lastPollTime
    string

    Time in seconds since epoch when the IBM Cloud platform will stop polling. This value will change for subsequent last_operation calls if the poll_after is specified in response to current last_operation call.

GetLastOperationOptions

The getLastOperation options.

parameters

  • instance_id
    Required*
    str

    The unique instance ID generated during provisioning by the IBM Cloud platform.

  • operation
    str

    A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for provision and update, and deprovision requests, the IBM Cloud platform provides the same value by using this query parameter as a URL-encoded string. If present, must be a non-empty string.

  • plan_id
    str

    ID of the plan from the catalog.json in your broker. If present, must be a non-empty string.

  • service_id
    str

    ID of the service from the catalog.json in your service broker. If present, must be a non-empty string.

  • last_poll_time
    str

    Time in seconds since epoch when the IBM Cloud platform will stop polling. This value will change for subsequent last_operation calls if the poll_after is specified in response to current last_operation call.

  • curl -X GET -H "Accept:application/json" -H "X-Broker-Api-Version:2.12" -u "TestServiceBrokerUser:TestServiceBrokerPassword" "http://localhost:3000/v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3A%3A/last_operation?operation=Provision_45&plan_id=e62e2c19-0c3b-41e3-b8b3-c71762ecd489&service_id=cb55391b-3416-4943-a6a6-a541778c1924"
  • options := openServiceBrokerService.NewGetLastOperationOptions(
  instanceId,
)
options = options.SetOperation(operation)
options = options.SetPlanID(planId)
options = options.SetServiceID(serviceId)

result, response, err := openServiceBrokerService.GetLastOperation(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • GetLastOperationOptions getLastOperationOptions = new GetLastOperationOptions.Builder()
  .instanceId(instanceId)
  .operation(operation)
  .planId(planId)
  .serviceId(serviceId)
  .build();

Response<Resp2079894Root> response = service.getLastOperation(getLastOperationOptions).execute();
Resp2079894Root result = response.getResult();

System.out.println(result);
  • const params = {
  instanceId: instanceId,
  operation: operation,
  planId: planId,
  serviceId: serviceId,
};

openServiceBrokerService.getLastOperation(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.get_last_operation(
  instance_id=instanceId,
  operation = operation,
  plan_id = planId,
  service_id = serviceId
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

InstanceLastOperationResp

Instance Last Operation response body

InstanceLastOperationResp

Instance Last Operation response body.

InstanceLastOperationResp

Instance Last Operation response body.

InstanceLastOperationResp

Instance Last Operation response body.

InstanceLastOperationResp

Instance Last Operation response body.

Status Code

  • 200

    OK - must be returned upon successful processing of this request.

  • 404

    NotFound - The platform will consider this response a success and remove the resource from its database. The expected response body is {}.

  • 410

    Gone - The platform will consider this response a success and remove the resource from its database. The expected response body is {}.

Example responses
  • {
  "state": "succeeded",
  "description": "The asynchronous creation of your service instance succeeded."
}
  • {
  "state": "succeeded",
  "description": "The asynchronous creation of your service instance succeeded."
}
  • {}
  • {}
  • {}
  • {}

Bind a service instance to another resource

Create a service binding on a service instance. If your service can be bound to applications in IBM Cloud, bindable:true must be specified in the catalog.json of your service broker. If bindable, it must be able to return API endpoints and credentials to your service consumers.

Note: Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

See the OSB 2.12 spec for more details on binding

Create a service binding on a service instance. If your service can be bound to applications in IBM Cloud, bindable:true must be specified in the catalog.json of your service broker. If bindable, it must be able to return API endpoints and credentials to your service consumers.

Note: Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

See the OSB 2.12 spec for more details on binding.

Create a service binding on a service instance. If your service can be bound to applications in IBM Cloud, bindable:true must be specified in the catalog.json of your service broker. If bindable, it must be able to return API endpoints and credentials to your service consumers.

Note: Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

See the OSB 2.12 spec for more details on binding.

Create a service binding on a service instance. If your service can be bound to applications in IBM Cloud, bindable:true must be specified in the catalog.json of your service broker. If bindable, it must be able to return API endpoints and credentials to your service consumers.

Note: Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

See the OSB 2.12 spec for more details on binding.

Create a service binding on a service instance. If your service can be bound to applications in IBM Cloud, bindable:true must be specified in the catalog.json of your service broker. If bindable, it must be able to return API endpoints and credentials to your service consumers.

Note: Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

See the OSB 2.12 spec for more details on binding.

PUT /v2/service_instances/{instance_id}/service_bindings/{binding_id}
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceBinding(replaceServiceBindingOptions *ReplaceServiceBindingOptions) (result *BindingPutResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) ReplaceServiceBindingWithContext(ctx context.Context, replaceServiceBindingOptions *ReplaceServiceBindingOptions) (result *BindingPutResp, response *core.DetailedResponse, err error)
replaceServiceBinding(params)
ServiceCall<BindingPutResp> replaceServiceBinding(ReplaceServiceBindingOptions replaceServiceBindingOptions)
replace_service_binding(self,
        binding_id: str,
        instance_id: str,
        *,
        plan_id: str = None,
        service_id: str = None,
        bind_resource: 'BindResource' = None,
        parameters: dict = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the ReplaceServiceBindingOptions struct and set the fields to provide parameter values for the ReplaceServiceBinding method.

Use the ReplaceServiceBindingOptions.Builder to create a ReplaceServiceBindingOptions object that contains the parameter values for the replaceServiceBinding method.

Path Parameters

  • binding_id
    Required*
    string

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instance_id
    Required*
    string

    The :instance_id is the ID of a previously provisioned service instance.

Request Body

BindingPutReq

Request body

parameter

WithContext method only

ReplaceServiceBindingOptions

The ReplaceServiceBinding options.

parameters

  • bindingId
    Required*
    string

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instanceId
    Required*
    string

    The :instance_id is the ID of a previously provisioned service instance.

  • planId
    string

    The ID of the plan from the catalog.json in your broker. If present, it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • serviceId
    string

    The ID of the service from the catalog.json in your broker. If present, it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • bindResource

    A JSON object that contains data for platform resources associated with the binding to be created.

  • parameters
    JsonObject

    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.

ReplaceServiceBindingOptions

The replaceServiceBinding options.

parameters

  • binding_id
    Required*
    str

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instance_id
    Required*
    str

    The :instance_id is the ID of a previously provisioned service instance.

  • plan_id
    str

    The ID of the plan from the catalog.json in your broker. If present, it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • service_id
    str

    The ID of the service from the catalog.json in your broker. If present, it must be a non-empty string.

    Examples:
    value
    _source
    _lines
    _html
  • bind_resource

    A JSON object that contains data for platform resources associated with the binding to be created.

  • parameters
    dict

    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.

  •  curl -X PUT -H "Accept:application/json" -H "Content-Type:application/json" -H "X-Broker-Api-Version:2.12" -H "X-Broker-Api-Originating-Identity:ibmcloud eyJpYW1faWQiOiJJQk1pZC0zMTAwMDJNNEpGIiwic3ViIjoiYmx1ZW1peF91aV9zb3Rlc3RAbWFpbGluYXRvci5jb20ifQ==" -u "TestServiceBrokerUser:TestServiceBrokerPassword" -d "{"bind_resource":{"app_guid":"d3f16a48-8bd1-4aab-a7de-e2a22ad38292"}, "parameters":{"parameter1":1, "parameter2":"value"}, "plan_id":"e62e2c19-0c3b-41e3-b8b3-c71762ecd489", "service_id":"cb55391b-3416-4943-a6a6-a541778c1924"}" http://localhost:3000/v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3A%3A/service_bindings/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3Aresource-key%3A92dba2e9-86e7-4bb6-8e9f-b14294a41cbd/
  • paramsOpt := make(map[string]string, 0)
paramsOpt["example"] = "property"

bindResource := &openservicebrokerv1.BindResource{
  AccountID:    &accountId,
  ServiceidCrn: &appGuid,
}

options := openServiceBrokerService.NewReplaceServiceBindingOptions(
  bindingId,
  instanceId,
)
options = options.SetPlanID(planId)
options = options.SetServiceID(serviceId)
options = options.SetParameters(paramsOpt)
options = options.SetBindResource(bindResource)

result, response, err := openServiceBrokerService.ReplaceServiceBinding(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • Map<String, String> param = new HashMap<String, String>();
param.put("example", "property");

BindResource bindRes = new BindResource.Builder()
    .accountId(accountId)
    .serviceidCrn(appGuid)
    .build();

ReplaceServiceBindingOptions replaceServiceBindingOptions = new ReplaceServiceBindingOptions.Builder()
  .instanceId(instanceId)
  .bindingId(bindingId)
  .planId(planId)
  .serviceId(serviceId)
  .parameters(param)
  .bindResource(bindRes)
  .build();

Response<Resp2079876Root> response = service.replaceServiceBinding(replaceServiceBindingOptions).execute();
Resp2079876Root result = response.getResult();

System.out.println(result);
  • const pars = { example: 'property'};

const bindResource = {
  account_id: accountId,
  serviceid_crn: appGuid,
};

const params = {
  bindingId: bindingId,
  bindResource: bindResource,
  instanceId: instanceId,
  planId: planId,
  serviceId: serviceId,
  parameters: pars,
};

openServiceBrokerService.replaceServiceBinding(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • bindResource = BindResource(
  account_id=accountId,
  serviceid_crn=appGuid
)
pars = {}
response = open_service_broker_service.replace_service_binding(
  binding_id=bindingId,
  instance_id=instanceId,
  plan_id=planId,
  service_id=serviceId,
  bind_resource=bindResource,
  parameters=pars
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

BindingPutResp

Binding PUT response body

BindingPutResp

Binding PUT response body.

BindingPutResp

Binding PUT response body.

BindingPutResp

Binding PUT response body.

BindingPutResp

Binding PUT response body.

Status Code

  • 200

    OK - must be returned if the binding exists and the requested parameters are identical to the existing binding.

  • 422

    Must be returned if the request could not be processed by the broker. For example, the broker requires that app_guid is included in the request body.

Example responses
  • {
  "credentials": {
    "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
    "username": "mysqluser",
    "password": "pass",
    "host": "mysqlhost",
    "port": 3306,
    "database": "dbname"
  }
}
  • {
  "credentials": {
    "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
    "username": "mysqluser",
    "password": "pass",
    "host": "mysqlhost",
    "port": 3306,
    "database": "dbname"
  }
}

Delete (unbind) the credentials that are bound to a resource

Delete instance binding by CRN. When a broker receives an unbind request from the IBM Cloud platform, it must delete any resources that are associated with the binding. In the case where credentials were generated, this might result in requests to the service instance failing to authenticate.

Note: Brokers that do not provide any bindable services or plans do not need to implement this endpoint.

Delete instance binding by CRN. When a broker receives an unbind request from the IBM Cloud platform, it must delete any resources that are associated with the binding. In the case where credentials were generated, this might result in requests to the service instance failing to authenticate.

Note: Brokers that do not provide any bindable services or plans do not need to implement this endpoint.

Delete instance binding by CRN. When a broker receives an unbind request from the IBM Cloud platform, it must delete any resources that are associated with the binding. In the case where credentials were generated, this might result in requests to the service instance failing to authenticate.

Note: Brokers that do not provide any bindable services or plans do not need to implement this endpoint.

Delete instance binding by CRN. When a broker receives an unbind request from the IBM Cloud platform, it must delete any resources that are associated with the binding. In the case where credentials were generated, this might result in requests to the service instance failing to authenticate.

Note: Brokers that do not provide any bindable services or plans do not need to implement this endpoint.

Delete instance binding by CRN. When a broker receives an unbind request from the IBM Cloud platform, it must delete any resources that are associated with the binding. In the case where credentials were generated, this might result in requests to the service instance failing to authenticate.

Note: Brokers that do not provide any bindable services or plans do not need to implement this endpoint.

DELETE /v2/service_instances/{instance_id}/service_bindings/{binding_id}
(openServiceBroker *OpenServiceBrokerV1) DeleteServiceBinding(deleteServiceBindingOptions *DeleteServiceBindingOptions) (response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) DeleteServiceBindingWithContext(ctx context.Context, deleteServiceBindingOptions *DeleteServiceBindingOptions) (response *core.DetailedResponse, err error)
deleteServiceBinding(params)
ServiceCall<Void> deleteServiceBinding(DeleteServiceBindingOptions deleteServiceBindingOptions)
delete_service_binding(self,
        binding_id: str,
        instance_id: str,
        plan_id: str,
        service_id: str,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the DeleteServiceBindingOptions struct and set the fields to provide parameter values for the DeleteServiceBinding method.

Use the DeleteServiceBindingOptions.Builder to create a DeleteServiceBindingOptions object that contains the parameter values for the deleteServiceBinding method.

Path Parameters

  • binding_id
    Required*
    string

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instance_id
    Required*
    string

    The :instance_id is the ID of a previously provisioned service instance.

Query Parameters

  • plan_id
    Required*
    string

    The ID of the plan from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

  • service_id
    Required*
    string

    The ID of the service from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

parameter

WithContext method only

DeleteServiceBindingOptions

The DeleteServiceBinding options.

parameters

  • bindingId
    Required*
    string

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instanceId
    Required*
    string

    The :instance_id is the ID of a previously provisioned service instance.

  • planId
    Required*
    string

    The ID of the plan from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

  • serviceId
    Required*
    string

    The ID of the service from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

DeleteServiceBindingOptions

The deleteServiceBinding options.

parameters

  • binding_id
    Required*
    str

    The binding_id is provided by the IBM Cloud platform. This ID will be used for future unbind requests, so the broker can use it to correlate the resource it creates.

  • instance_id
    Required*
    str

    The :instance_id is the ID of a previously provisioned service instance.

  • plan_id
    Required*
    str

    The ID of the plan from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

  • service_id
    Required*
    str

    The ID of the service from the catalog.json in the broker. It must be a non-empty string and should be a GUID.

  •  curl -X DELETE -H "Accept:application/json" -H "X-Broker-Api-Version:2.12" -H "X-Broker-Api-Originating-Identity:ibmcloud eyJpYW1faWQiOiJJQk1pZC0zMTAwMDJNNEpGIiwic3ViIjoiYmx1ZW1peF91aV9zb3Rlc3RAbWFpbGluYXRvci5jb20ifQ==" -u "TestServiceBrokerUser:TestServiceBrokerPassword" "http://localhost:3000/v2/service_instances/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3A%3A/service_bindings/crn%3Av1%3Abluemix%3Apublic%3Atestjavaresourceservicebrokername%3Aus-south%3Aa%2F499b176abb3e1c9727df87ae48b27c7b%3A7f0d2b93-fd4a-4ce9-8675-978d20b1e0b7%3Aresource-key%3A92dba2e9-86e7-4bb6-8e9f-b14294a41cbd?plan_id=e62e2c19-0c3b-41e3-b8b3-c71762ecd489&service_id=cb55391b-3416-4943-a6a6-a541778c1924"
  • deleteServiceBindingOptions := openServiceBrokerService.NewDeleteServiceBindingOptions(
  bindingId,
  instanceId,
  planId,
  serviceId,
)

response, err := openServiceBrokerService.DeleteServiceBinding(deleteServiceBindingOptions)
if err != nil {
  panic(err)
}
  • DeleteServiceBindingOptions deleteServiceBindingOptions = new DeleteServiceBindingOptions.Builder()
  .bindingId(bindingId)
  .instanceId(instanceId)
  .planId(planId)
  .serviceId(serviceId)
  .build();

service.deleteServiceBinding(deleteServiceBindingOptions).execute();
  • const params = {
  bindingId: bindingId,
  instanceId: instanceId,
  planId: planId,
  serviceId: serviceId,
};

openServiceBrokerService.deleteServiceBinding(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.delete_service_binding(
  binding_id=bindingId,
  instance_id=instanceId,
  plan_id=planId,
  service_id=serviceId,
).get_result()

print(json.dumps(response, indent=2))

Response

Response Body

object

Status Code

  • 200

    OK - must be returned if the binding was deleted as a result of this request. The expected response body is {}.

  • 410

    Gone - must be returned if the binding does not exist. The expected response body is {}.

  • 422

    Must be returned if the request could not be processed by the broker.

Example responses
  • {}
  • {}
  • {}
  • {}
  • {
  "error": "DependencyError",
  "description": "Unable to process request due to dependency X."
}
  • {
  "error": "DependencyError",
  "description": "Unable to process request due to dependency X."
}

Get the catalog metadata stored within the broker

This endpoint defines the contract between the broker and the IBM Cloud platform for the services and plans that the broker supports. This endpoint returns the catalog metadata that is stored within your broker. These values define the minimal provisioning contract between your service and the IBM Cloud platform.

All additional catalog metadata that is not required for provisioning is stored within the IBM Cloud catalog, and any updates to catalog display values that are used to render your dashboard like links, icons, and i18n translated metadata should be updated in Partner Center, and not housed in your broker. None of the metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI returns what was set within Partner Center and stored in the IBM Cloud catalog.

This endpoint defines the contract between the broker and the IBM Cloud platform for the services and plans that the broker supports. This endpoint returns the catalog metadata that is stored within your broker. These values define the minimal provisioning contract between your service and the IBM Cloud platform.

All additional catalog metadata that is not required for provisioning is stored within the IBM Cloud catalog, and any updates to catalog display values that are used to render your dashboard like links, icons, and i18n translated metadata should be updated in the Resource Management Console (RMC), and not housed in your broker. None of the metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI returns what was set within RMC and stored in the IBM Cloud catalog.

This endpoint defines the contract between the broker and the IBM Cloud platform for the services and plans that the broker supports. This endpoint returns the catalog metadata that is stored within your broker. These values define the minimal provisioning contract between your service and the IBM Cloud platform.

All additional catalog metadata that is not required for provisioning is stored within the IBM Cloud catalog, and any updates to catalog display values that are used to render your dashboard like links, icons, and i18n translated metadata should be updated in the Resource Management Console (RMC), and not housed in your broker. None of the metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI returns what was set within RMC and stored in the IBM Cloud catalog.

This endpoint defines the contract between the broker and the IBM Cloud platform for the services and plans that the broker supports. This endpoint returns the catalog metadata that is stored within your broker. These values define the minimal provisioning contract between your service and the IBM Cloud platform.

All additional catalog metadata that is not required for provisioning is stored within the IBM Cloud catalog, and any updates to catalog display values that are used to render your dashboard like links, icons, and i18n translated metadata should be updated in the Resource Management Console (RMC), and not housed in your broker. None of the metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI returns what was set within RMC and stored in the IBM Cloud catalog.

This endpoint defines the contract between the broker and the IBM Cloud platform for the services and plans that the broker supports. This endpoint returns the catalog metadata that is stored within your broker. These values define the minimal provisioning contract between your service and the IBM Cloud platform.

All additional catalog metadata that is not required for provisioning is stored within the IBM Cloud catalog, and any updates to catalog display values that are used to render your dashboard like links, icons, and i18n translated metadata should be updated in the Resource Management Console (RMC), and not housed in your broker. None of the metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI returns what was set within RMC and stored in the IBM Cloud catalog.

GET /v2/catalog
(openServiceBroker *OpenServiceBrokerV1) ListCatalog(listCatalogOptions *ListCatalogOptions) (result *BrokerCatalogResp, response *core.DetailedResponse, err error)
(openServiceBroker *OpenServiceBrokerV1) ListCatalogWithContext(ctx context.Context, listCatalogOptions *ListCatalogOptions) (result *BrokerCatalogResp, response *core.DetailedResponse, err error)
listCatalog(params)
ServiceCall<BrokerCatalogResp> listCatalog()
list_catalog(self,
        **kwargs
    ) -> DetailedResponse

Request

No Request Parameters

This method does not accept any request parameters.

parameter

WithContext method only

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET -H "Accept:application/json" -H "X-Broker-Api-Version:2.12" -u "TestServiceBrokerUser:TestServiceBrokerPassword" http://localhost:3000/v2/catalog
  • options := openServiceBrokerService.NewListCatalogOptions()

result, response, err := openServiceBrokerService.ListCatalog(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(b))
  • ListCatalogOptions listCatalogOptions = new ListCatalogOptions();

Response<Resp1874650Root> response = service.listCatalog(listCatalogOptions).execute();
Resp1874650Root result = response.getResult();

System.out.println(result);
  • openServiceBrokerService.listCatalog({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • response = open_service_broker_service.list_catalog().get_result()

print(json.dumps(response, indent=2))

Response

Response Body

BrokerCatalogResp

Broker Catalog GET response body

BrokerCatalogResp

Broker Catalog GET response body.

BrokerCatalogResp

Broker Catalog GET response body.

BrokerCatalogResp

Broker Catalog GET response body.

BrokerCatalogResp

Broker Catalog GET response body.

Status Code

  • 200

    200 OK

Example responses
  • {
  "services": [
    {
      "bindable": true,
      "description": "Test Node Resource Service Broker Description",
      "id": "service-guid-here",
      "metadata": {
        "displayName": "Test Node Resource Service Broker Display Name",
        "documentationUrl": "http://10.0.1.2/documentation.html",
        "imageUrl": "http://10.0.1.2/servicesample.png",
        "instructionsUrl": "http://10.0.1.2/servicesample.md",
        "longDescription": "Test Node Resource Service Broker Plan Long Description",
        "providerDisplayName": "Some Company",
        "supportUrl": "http://10.0.1.2/support.html",
        "termsUrl": "http://10.0.1.2/terms.html"
      },
      "name": "testnoderesourceservicebrokername",
      "plan_updateable": true,
      "tags": [
        "lite",
        "tag1a",
        "tag1b"
      ],
      "plans": [
        {
          "description": "Test Node Resource Service Broker Plan Description",
          "free": true,
          "id": "plan-guid-here",
          "metadata": {
            "bullets": [
              "Test bullet 1",
              "Test bullet 2"
            ],
            "displayName": "Lite"
          },
          "name": "lite"
        }
      ]
    }
  ]
}
  • {
  "services": [
    {
      "bindable": true,
      "description": "Test Node Resource Service Broker Description",
      "id": "service-guid-here",
      "metadata": {
        "displayName": "Test Node Resource Service Broker Display Name",
        "documentationUrl": "http://10.0.1.2/documentation.html",
        "imageUrl": "http://10.0.1.2/servicesample.png",
        "instructionsUrl": "http://10.0.1.2/servicesample.md",
        "longDescription": "Test Node Resource Service Broker Plan Long Description",
        "providerDisplayName": "Some Company",
        "supportUrl": "http://10.0.1.2/support.html",
        "termsUrl": "http://10.0.1.2/terms.html"
      },
      "name": "testnoderesourceservicebrokername",
      "plan_updateable": true,
      "tags": [
        "lite",
        "tag1a",
        "tag1b"
      ],
      "plans": [
        {
          "description": "Test Node Resource Service Broker Plan Description",
          "free": true,
          "id": "plan-guid-here",
          "metadata": {
            "bullets": [
              "Test bullet 1",
              "Test bullet 2"
            ],
            "displayName": "Lite"
          },
          "name": "lite"
        }
      ]
    }
  ]
}