Get the current state of the service instance

GET /bluemix_v1/service_instances/{instance_id}

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.

Request

Path Parameters

Query Parameters

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

Response

200 - OK

active

boolean

Indicates (from the viewpoint of the provider) whether the service instance is active and is meaningful if enabled is true. The default value is true if not specified.

enabled

boolean

Indicates the current state of the service instance.

last_active

number

The timestamp in seconds since the Unix epoch, indicating when the service instance was last accessed, modified, or otherwise interacted with. This value is meaningful only if both enabled is true and active is false.

Update the state of a provisioned service instance

PUT /bluemix_v1/service_instances/{instance_id}

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

Request

Request Body

InstanceStatePutReq

enabled

Required *

boolean

Indicates the current state of the service instance.

initiator_id

string

The IAM ID of the user that initiated the call.

reason_code

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.<br/><br/>Previously accepted values had a `BMX_` prefix, such as `BMX_ACCT_ACTIVATE`. These values are deprecated.

Path Parameters

Query Parameters

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

Response

200 - OK

active

boolean

Indicates (from the viewpoint of the provider) whether the service instance is active and is meaningful if enabled is true. The default value is true if not specified.

enabled

boolean

Indicates the current state of the service instance.

last_active

number

The timestamp in seconds since the Unix epoch, indicating when the service instance was last accessed, modified, or otherwise interacted with. This value is meaningful only if both enabled is true and active is false.

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

description

string

Description of error

Create (provision) a service instance

PUT /v2/service_instances/{instance_id}

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/service_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 header has the IBM IAM ID of the user that initiated the request

Request

Request Body

InstancePutReq

Request body

context

Required *

Context

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

account_id

Required *

string

Returns the ID of the account in IBM Cloud that is provisioning the service instance.

crn

Required *

string

When a customer provisions your service in IBM Cloud, a service instance is created and this instance is identified by its IBM Cloud Resource Name (CRN). The CRN is used in all aspects of the interaction with IBM Cloud including provisioning, binding (creating credentials and endpoints), metering, dashboard display, and access control. From a service provider perspective, the CRN can largely be treated as an opaque string to be used with the IBM Cloud APIs, but it can also be decomposed through the following structure: `crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource`

platform

Required *

string

Identifies the platform as "ibmcloud"

resource_group_crn

Required *

string

The ID of the resource group

target_crn

Required *

string

The deployment target where the instance should be hosted.

name

Required *

string

Name of the instance

organization_guid

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.

parameters

Parameters

Configuration options for the service instance or binding operation. 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 or binindg as a result of this request.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

space_guid

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.

Response

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

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

cancelable

boolean

Indicates if the resource's last operation can be canceled. If cancelable is true, the IBM Cloud platform may call the Service Instance `last_operation_cancel` Endpoint to cancel the last operation.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

cancelable

boolean

Indicates if the resource's last operation can be canceled. If cancelable is true, the IBM Cloud platform may call the Service Instance `last_operation_cancel` Endpoint to cancel the last operation.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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.

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

cancelable

boolean

Indicates if the resource's last operation can be canceled. If cancelable is true, the IBM Cloud platform may call the Service Instance `last_operation_cancel` Endpoint to cancel the last operation.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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.

description

string

Description of error

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`

description

string

Description of error

Update a service instance

PATCH /v2/service_instances/{instance_id}

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.

When an instance update 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 header has the IBM IAM ID of the user that initiated the request

Request

Request Body

InstancePatchReq

Request body

context

Context

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

account_id

Required *

string

Returns the ID of the account in IBM Cloud that is provisioning the service instance.

crn

Required *

string

When a customer provisions your service in IBM Cloud, a service instance is created and this instance is identified by its IBM Cloud Resource Name (CRN). The CRN is used in all aspects of the interaction with IBM Cloud including provisioning, binding (creating credentials and endpoints), metering, dashboard display, and access control. From a service provider perspective, the CRN can largely be treated as an opaque string to be used with the IBM Cloud APIs, but it can also be decomposed through the following structure: `crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource`

platform

Required *

string

Identifies the platform as "ibmcloud"

resource_group_crn

Required *

string

The ID of the resource group

target_crn

Required *

string

The deployment target where the instance should be hosted.

name

Required *

string

Name of the instance

parameters

Parameters

Configuration options for the service instance or binding operation. 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 or binindg as a result of this request.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

previous_values

PreviousValues

Information about the service instance before the update.

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

Response

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

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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.

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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`

description

string

Description of error

Delete (deprovision) a service instance

DELETE /v2/service_instances/{instance_id}

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.

When you delete an instance, the IBM Cloud platform provides the following values:

  • The X-Broker-API-Originating-Identity header has the IBM IAM ID of the user that initiated the request

Request

Path Parameters

Query Parameters

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

instance_name

Required *

string

The name of the instance for which the service instance is requested.

Response

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.

operation

string

For asynchronous responses, service brokers might return an identifier that represents the operation. The value of this field must be provided by the platform with requests to the `last_operation` endpoint in a URL encoded query parameter. If present, must be a non-empty string.

poll_after

number

For asynchronous responses, the number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

poll

boolean

For asynchronous responses, indicates if the IBM Cloud platform to poll the Service Instance `last_operation` Endpoint for operation status.

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

description

string

Description of error

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`

description

string

Description of error

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

GET /v2/service_instances/{instance_id}/last_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.

Request

Path Parameters

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

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

last_poll_time

Required *

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.

Response

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

description

string

A user-facing message displayed to the platform API client. Can be used to tell the user details about the status of the operation. If present, must be a non-empty string.

state

string

A response with state `in progress` will cause the platform to continue polling while responses with `succeeded` or `failed` will cause the platform to stop polling.'

dashboard_url

string

The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL must contain enough information for the dashboard to identify the resource that is being accessed. If present, must be a non-empty string.

extensions

object

Additional instance properties contributed by the service that are represented as key-value pairs. These properties be persisted with the instance under the `extensions` property.

poll_after

number

Number of seconds after which the IBM Cloud platform will make the next `last_operation` call. If value is less than 10, it defaults to 10 seconds.

cancelable

boolean

Indicates if the resource's last operation can be canceled. If cancelable is true, the IBM Cloud platform may call the Service Instance `last_operation_cancel` Endpoint to cancel the last operation.

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

description

string

Description of error

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

description

string

Description of error

binding">

Bind a service instance to another resource

PUT /v2/service_instances/{instance_id}/service_bindings/{binding_id}

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.

When you create a binding, the IBM Cloud platform provides the following values:

  • The X-Broker-API-Originating-Identity header has the IBM IAM ID of the user that initiated the request

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

Request

Request Body

BindingPutReq

Request body

bind_resource

BindResource

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

app_guid

string

GUID of an application associated with the binding. For credentials bindings.

route

string

URL of the application to be intermediated. For route services bindings.

parameters

Parameters

Configuration options for the service instance or binding operation. 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 or binindg as a result of this request.

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

Response

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

credentials

object

A free-form hash of credentials that can be used by applications or users to access the service.

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.

description

string

Description of error

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

DELETE /v2/service_instances/{instance_id}/service_bindings/{binding_id}

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.

When you delete a binding, the IBM Cloud platform provides the following values:

  • The X-Broker-API-Originating-Identity header has the IBM IAM ID of the user that initiated the request

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

Request

Path Parameters

Query Parameters

plan_id

Required *

string

The unique identifier (GUID) of the plan associated with the requested service instance, as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

service_id

Required *

string

The unique identifier (GUID) for the service as defined in the catalog.json file of your broker. This parameter must be a non-empty string.

Response

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 {}.

description

string

Description of error

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

description

string

Description of error

Get the catalog metadata stored within the broker

GET /v2/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.

Request

Response

200 - 200 OK

services

array

List of services