Introduction

Service Brokers manage the lifecycle of Services. The IBM Cloud platform interacts with Service Brokers to provision and manage Service Instances (an instantiation of a Service offering) and Service Bindings (The representation of an association between an Application and a Service Instance, which often contain the credentials that the Application will use to communicate with the Service Instance). Providing valid metadata values will create a successful Rest API Response when a Request a performed.

The The IBM Cloud Open Service Broker API provides endpoints service providers can use to enable provisioning, binding, and more. The IBM Cloud Open Service Broker API also extends the Open Service Broker API (OSB) specification by providing endpoints that allow providers to enable and disable provisioned service instances.

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, 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 or brokers will receive the following information from the IBM Cloud platform:

X-Broker-API-Originating-Identity

The user identity header will be provided via an API originating identity header. This request header will include the user's IBM Cloud IAM Identity. The IAM Identity will be 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 will be 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 will receive the following value within body.context: { "platform": "ibmcloud", "account_id": "tracys-account-id", "crn": "resource-instance-crn" }.

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 less then 10 seconds, then synchronous responses are recommended. Otherwise, you should use the asynchronous mode of operation. More information on this is contained in the OSB specification.

If your async operation takes less than 10 seconds when trying to provision an instance, the platform will time-out.

Error handling

The IBM Cloud 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 some sort of failure, and a 500 type response usually indicates an internal system error.

When implementing IBM Cloud Open Service Broker API endpoints, you might find the Resource Controller and Resource Manager APIs useful.

Methods

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 may need a to disable the service (without deleting it), and when the account is settled re-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 may 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}
Request

Path Parameters

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

Example requests
Response

Status Code

  • OK

Example responses

Update the state of a provisioned service instance

Update (disable or enable) the state of a provisioned service instance. As a service provider you need a way to manage provisioned service instances. If an account comes past due, you may need a to disable the service (without deleting it), and when the account is settled re-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 / disable request, it should take whatever action is necessary to enable / disable (respectively) the service. Additionally, If a bind request comes in 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}
Request

Path Parameters

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

Example requests
Response

Status Code

  • No Content

Example responses

Create (provision) a service instance

Create a service instance with GUID. 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 using IBM Cloud IAM. After this validation occurs, your service broker's provision endpoint (PUT /v2/resource_instances/:instance_id) will be 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 will have the IBM IAM ID of the user that initiated the request
  • The parameters section will include the requested location (and additional parameters required by your service).
PUT /v2/service_instances/{instance_id}
Request

Path Parameters

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

Query Parameters

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

Response body

Example requests
Response

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

Status Code

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

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

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

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

  • Unprocessable Entity

Example responses

Update a service instance

Patch an instance by GUID. 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 will need to 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}
Request

Path Parameters

  • The ID of a previously provisioned service instance

Query Parameters

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

Request body

Example requests
Response

Status Code

  • OK

  • Accepted

  • Unprocessable Entity

No Sample Response

This method does not specify any sample responses.

Delete (deprovision) a service instance

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

DELETE /v2/service_instances/{instance_id}
Request

Path Parameters

  • The ID of a previously provisioned service instance

Query Parameters

  • The ID of the plan for which the service instance has been requested, which is stored in the catalog.json of your broker. This value should be a GUID. MUST be a non-empty 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.

  • 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 only deprovision a service instance of the requested plan asynchronously, the broker MUST reject the request with a 422 Unprocessable Entity.

Example requests
Response

Status Code

  • OK

  • Accepted

  • Gone

  • MUST be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true

Example responses

Get the catalog metadata stored within the broker

This endpoints 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 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 metadata stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI; the console and CLI will return what was set withn RMC and stored in the IBM Cloud catalog.

GET /v2/catalog
Request

No Request Parameters

This method does not accept any request parameters.

Example requests
Response

Status Code

  • 200 OK

Example responses

Get the current status of a provision in-progress for a service instance

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

Valid values for state are in progress, succeeded, and failed. The platform will poll the last_operationendpoint as long as the broker returns "state": "in progress". Returning "state": "succeeded" or "state": "failed" will cause the platform to cease polling. The value provided for description will be passed through to the platform API client and can be used to provide additional detail for users about the progress of the operation.

GET /v2/service_instances/{instance_id}/last_operation
Request

Path Parameters

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

Query Parameters

  • 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 will provide the same value using this query parameter as a URL-encoded string. If present, MUST be a non-empty string.

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

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

Example requests
Response

Status Code

  • OK - MUST be returned upon successful processing of this request.

  • Gone - Appropriate only for asynchronous delete operations. The platform MUST consider this response a success and remove the resource from its database. The expected response body is {}. Returning this while the platform is polling for create or update operations SHOULD be interpreted as an invalid response and the platform SHOULD continue polling.

Example responses

Bind a service instance to another resource

Create binding by GUID on 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}
Request

Path Parameters

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

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

Request body

Example requests
Response

Status Code

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

  • Unprocessable Entity

No Sample Response

This method does not specify any sample responses.

Delete (unbind) the credentials bound to a resource

Delete instance binding by GUID.

When a broker receives an unbind request from the IBM Cloud platform, it MUST delete any resources 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}
Request

Path Parameters

  • The binding_id is the ID of a previously provisioned binding for that service instance.

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

Query Parameters

  • ID of the plan from the catalog.json in the broker. MUST be a non-empty string. Should be a GUID.

  • ID of the service from the catalog.json in the broker. MUST be a non-empty string. Should be a GUID.

Example requests
Response

Status Code

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

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

No Sample Response

This method does not specify any sample responses.