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