Developing, hosting, and testing your service brokers

Required endpoint logic for all service brokers

Service brokers must provide a standard set of metadata values that are consumed by REST APIs, and IBM Cloud brokers must have logic for the following REST API endpoints or paths:

catalog (GET)

Returns your catalog metadata included in your broker.

resource instances (PUT)

Creates your service instance.

resource instances (DELETE)

Deletes your service instance.

resource instances (PATCH)

Updates your service instance.

Note on catalog (GET): 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 contract between your service and the IBM Cloud platform. All additional catalog metadata that isn't required is stored within the IBM Cloud catalog. Any updates to catalog display values like links and icons must be updated in the IBM Cloud console, and not housed in your broker. None of metadata that is stored in your broker is displayed in the IBM Cloud console or the IBM Cloud CLI. The console and CLI return what was set within Partner Center Sell and stored in the IBM Cloud catalog. The following section shows the minimal-required values that catalog (GET) returns:

{
       "services": [{
           "id": "0bc9d744-6f8c-4821-9648-2278bf6925bb",
           "name": "ibmcloud-link",
           "description": "An IBM provided service that enables aliasing to service instances in the IBM Cloud.",
           "bindable": true,
           "plan_updateable": false,
           "plans": [
               {
                   "id": "da40662d-2f72-4a19-8c79-8c77cf285e1",
                   "name": "ibmcloud-alias",
                   "free": true,
                   "description": "The IBM Cloud alias plan used for linking."
               }
               ]
       }]
}

Required endpoints logic for bindable services

If your service can be bound to applications in IBM Cloud, it must return API endpoints and credentials to your service consumers. A bindable service must use the bindable operations in the Open Service Broker specification, and implement the following endpoints or paths:

bindings and credentials (PUT)

Binds your service instance to an application.

bindings and credentials (DEL)

Unbinds your service instance from an application.

Required IBM Cloud extension endpoints

The OSB specification doesn't support a disabled instance state. A disabled state includes a missing payment or other situations that result in an account suspension (but not yet cancellation) and is different from a deleted instance state. In order for IBM Cloud to support customers that might experience a disabled state, IBM Cloud defined the extended API endpoints that allow service instances to be disabled and re-enabled. The following endpoint extensions are required:

enable and disable instances (GET)

Status - returns the state of your service instance.

enable and disable instances (PUT)

Enable or disable a service instance.

It's the service provider's responsibility to disable access to the service instance when the disable endpoint starts and to re-enable that access when the enable endpoint is started.

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

Recommendations on using asynchronous instead of synchronous operations

The OSB API supports both synchronous and asynchronous modes of operation. If your operations are going to take less than 10 seconds, you must use synchronous responses. Otherwise, you must use the asynchronous mode of operation. The asynchronous mode requires the last_operation endpoint. For more information, see Get the status of a provision in-progress for a service instance.

Recommendations for managing brokers across locations

It's important for users to understand the location of their cloud services for latency, availability, and data residency.

When you're creating service instances on IBM Cloud, one of the required parameters your users provide is the location where they want that service instance to be created. Some services can support creation in multiple locations. For example, a database service can support creation in all IBM Cloud regions or it can support a subset.

If your third-party API-based service is implemented in another cloud and exposed into IBM Cloud, the location indicates the service's location in the other cloud.

When you onboard to IBM Cloud, you must implement at least one OSB broker. You can have more than one broker depending on your deployment strategy and the locations you want to support for your service. Within Partner Center Sell, you establish the mapping between your pricing plan and the broker. The typical choices are to define a single broker to service all locations for your service or to define a broker per location; this choice is up to the service provider.

For a list of available locations, review the IBM global catalog locations. If your service requires more locations to be defined, consult the IBM Cloud onboarding team.