Introduction

The resource controller is the next-generation IBM Cloud platform provisioning layer that manages the lifecycle of IBM Cloud resources in a customer account. Resources is a broad term that could mean anything from an instance of a service like Cloudant, a Cloud Foundry application, a virtual machine, a container, a software image, a data set, or other entities associated to the customer account.

The resource controller provides common APIs to control the lifecycle of resources from provisioning (creating an instance) to binding (creating access credentials) to unbinding (removing access) to de-provisioning (deleting an instance). Resources are provisioned globally in an account scope. The resource controller supports both synchronous and asynchronous provisioning of resources.

Resources are created by the resource controller within resource groups. A resource group belongs to an account. All IBM Cloud resources must be provisioned within a resource group. If an account is suspended, the corresponding resource group are suspended as well, and all resources within the resource group are suspended.

Resource instances

When the resource controller provisions or creates and instance, provisioning reserves a resource on a service; we call this reserved resource a resource instance (service instance). What a resource instance represents can vary by service. Examples include a single database on a multi-tenant server, a dedicated cluster, or an account on a web application.

Resource bindings and keys

A resource binding is the representation of an association between an application and a resource (service) instance. Often, resource bindings will contain the credentials (keys) that the application will use to communicate with the resource instance. Keys are credentials used to connect (bind) a service to another application.

Resource aliases

You can think of an alias as a symlink in computing terms. It represents an entity that points back to a resource instance and enables you to define different access controls on it. As with symlinks you can also create multiple aliases to a single resource instance and manage each one separately.

For example, you can create an instance of a service and then reuse that instance in both London and Dallas by creating aliases in both regions. This enables you to bind keys (credentials) to applications that run in those regions and utilize the same logical instance.

API endpoint

https://resource-controller.bluemix.net/v2/

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
410 Gone The resource is valid but has been removed already in a previous call
500 Internal Server Error offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token in the API request authentication header:

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

To retrieve your access token:

curl -X POST
https://iam.bluemix.net/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --id

Replace <instance_name> with the unique alias that you assigned to your service instance.

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v2/resource_instances
  • /v2/resource_bindings
  • /v2/resource_keys
  • /v2/resource_aliases

The default page and max size is 100 objects. To use a different page size, use the limit query parameter.

For any request that uses pagination, the response includes a next_url object that specifies pagination information. next_url is the URL for requesting the next page of results. The next_url property is null if there are no more results, and retains the same limit parameter that is used for the initial request.

Rate limiting

Rate limits for API requests are enforced on a per-caller basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers you can use to determine whether you are close to the rate limit:

  • X-RateLimit-Reset: the time the current timer expires (in UNIX epoch time)
  • X-RateLimit-Remaining: the number of requests remaining in the current time window
  • X-RateLimit-Limit: the total number of requests allowed within the time window

An HTTP status code of 429 indicates that the rate limit has been exceeded.

The number of allowed requests, and the length of the time window, vary by method and endpoint. The reference information for each endpoint specifies the rate limit that applies.

When working with the resource controller endpoints, it may be helpful to be aware of the IBM Cloud Open Source Broker APIs used to create your service broker.

Methods

Get a list of all resource instances

Get a list of all resource instances.

GET /resource_instances
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • When you provision a new resource in the specified location for the selected plan, a GUID (globally unique identifier) is created. This is a unique internal GUID managed by Resource controller that corresponds to the instance.

  • The human-readable name of the instance.

  • Short ID of a resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

  • The type of the instance. For example, service_instance.

  • The sub-type of instance, e.g. cfaas.

  • Limit on how many items should be returned.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
Response

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Create (provision) a new resource instance

Provision a new resource in the specified location for the selected plan.

POST /resource_instances
Request

Custom Headers

  • Your IBM Cloud IAM access token.

  • The name of the instance.

    Example: my-instance

  • The deployment location where the instance should be hosted.

    Example: bluemix-us-south

  • Short or long ID of resource group

    Example: 5c49eabc-f5e8-5881-a37e-2d100a33b3df

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    Example: cloudant-standard

  • Configuration options represented as key-value pairs that are passed through to the target resource brokers.

Example request
curl -X POST \
  https://resource-controller.bluemix.net/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "bluemix-global",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "0be5ad401ae913d8ff665d92680664ed"
  }'
Response
  • The ID associated with the instance.

  • When you create a new resource, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the instance.

  • The full CRN (cloud resource name) associated with the instance. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new resource, a relative URL path is created identifying the location of the instance.

  • The human-readable name of the instance.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

  • The full deployment CRN (defined in the global catalog). The Cloud Resource Name (CRN) of the deployment location where the instance is provisioned.

  • The current state of the instance. For example, if the instance is deleted, it will return removed.

  • The type of the instance, e.g. service_instance.

  • The sub-type of instance, e.g. cfaas.

  • The status of the last operation requested on the instance.

  • The resource-broker-provided URL to access administrative features of the instance.

  • The plan history of the instance.

    • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    • The date in which the plan was changed.

  • The relative path to the resource aliases for the instance.

  • The relative path to the resource bindings for the instance.

  • The relative path to the resource keys for the instance.

  • The date when the instance was created.

  • The date when the instance was last updated.

  • The date when the instance was deleted.

Status Code

  • Instance has been provisioned

  • Request to provision a resource has been accepted.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get a resource instance

Retrieve a resource instance by ID.

GET /resource_instances/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the instance.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94 \
  -H 'Authorization: Bearer <>' \
Response
  • The ID associated with the instance.

  • When you create a new resource, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the instance.

  • The full CRN (cloud resource name) associated with the instance. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new resource, a relative URL path is created identifying the location of the instance.

  • The human-readable name of the instance.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

  • The full deployment CRN (defined in the global catalog). The Cloud Resource Name (CRN) of the deployment location where the instance is provisioned.

  • The current state of the instance. For example, if the instance is deleted, it will return removed.

  • The type of the instance, e.g. service_instance.

  • The sub-type of instance, e.g. cfaas.

  • The status of the last operation requested on the instance.

  • The resource-broker-provided URL to access administrative features of the instance.

  • The plan history of the instance.

    • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    • The date in which the plan was changed.

  • The relative path to the resource aliases for the instance.

  • The relative path to the resource bindings for the instance.

  • The relative path to the resource keys for the instance.

  • The date when the instance was created.

  • The date when the instance was last updated.

  • The date when the instance was deleted.

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Delete a resource instance

Delete a resource instance by ID.

DELETE /resource_instances/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the instance.

Example request
curl -X DELETE \
  https://resource-controller.bluemix.net/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94 \
  -H 'Authorization: Bearer <>' \
Response
  • The ID associated with the instance.

  • When you create a new resource, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the instance.

  • The full CRN (cloud resource name) associated with the instance. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new resource, a relative URL path is created identifying the location of the instance.

  • The human-readable name of the instance.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

  • The full deployment CRN (defined in the global catalog). The Cloud Resource Name (CRN) of the deployment location where the instance is provisioned.

  • The current state of the instance. For example, if the instance is deleted, it will return removed.

  • The type of the instance, e.g. service_instance.

  • The sub-type of instance, e.g. cfaas.

  • The status of the last operation requested on the instance.

  • The resource-broker-provided URL to access administrative features of the instance.

  • The plan history of the instance.

    • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    • The date in which the plan was changed.

  • The relative path to the resource aliases for the instance.

  • The relative path to the resource bindings for the instance.

  • The relative path to the resource keys for the instance.

  • The date when the instance was created.

  • The date when the instance was last updated.

  • The date when the instance was deleted.

Status Code

  • Accepted

  • Deleted

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The resource could was previously deleted and is no longer available.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This endpoint does not specify any sample responses.

Update a resource instance

Update a resource instance by ID.

PATCH /resource_instances/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the instance.

  • The new name of the instance.

    Example: my-new-instance-name

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    Example: a8dff6d3-d287-4668-a81d-c87c55c2656d

Example request
curl -X PATCH \
  https://resource-controller.bluemix.net/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94 \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance-new-binding-1",
    "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d"
  }'
Response
  • The ID associated with the instance.

  • When you create a new resource, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the instance.

  • The full CRN (cloud resource name) associated with the instance. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new resource, a relative URL path is created identifying the location of the instance.

  • The human-readable name of the instance.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

  • The full deployment CRN (defined in the global catalog). The Cloud Resource Name (CRN) of the deployment location where the instance is provisioned.

  • The current state of the instance. For example, if the instance is deleted, it will return removed.

  • The type of the instance, e.g. service_instance.

  • The sub-type of instance, e.g. cfaas.

  • The status of the last operation requested on the instance.

  • The resource-broker-provided URL to access administrative features of the instance.

  • The plan history of the instance.

    • The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.

    • The date in which the plan was changed.

  • The relative path to the resource aliases for the instance.

  • The relative path to the resource bindings for the instance.

  • The relative path to the resource keys for the instance.

  • The date when the instance was created.

  • The date when the instance was last updated.

  • The date when the instance was deleted.

Status Code

  • The requested changes have been applied

  • Request to update a resource instance has been accepted

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The request could not be processed.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get a list of resource keys

List all resource keys

GET /resource_keys
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • When you create a new key, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the key.

  • The human-readable name of the key.

  • The short ID of the resource group.

  • The unique ID of the offering. This value is provided by and stored in the global catalog.

  • Limit on how many items should be returned.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_keys \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Create a new resource key

Create a new resource key.

POST /resource_keys
Request

Custom Headers

  • Your IBM Cloud IAM access token.

  • The name of the key.

    Example: my-key

  • The short or long ID of resource instance or alias.

    Example: 25eba2a9-beef-450b-82cf-f5ad5e36c6dd

  • Configuration options represented as key-value pairs that are passed through to the target resource brokers.

  • The role name or it's CRN.

    Default: Manager

    Example: Manager

Example request
curl -X POST \
  https://resource-controller.bluemix.net/v2/resource_keys \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-instance-key-1",
  "source": "267bf377-7fa2-43f6-94ec-09103a8e89d4",
  "role": "Writer"
}'
Response
  • The ID associated with the key.

  • When you create a new key, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the key.

  • The full CRN (cloud resource name) associated with the key. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new key, a relative URL path is created identifying the location of the key.

  • The human-readable name of the key.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource instance or alias associated to the key.

  • The state of the key.

  • The credentials for the key. Additional key-value pairs are passed through from the resource brokers. Refer to service’s documentation for additional details.

  • Specifies whether the key’s credentials support IAM.

  • The relative path to the resource.

  • The date when the key was created.

  • The date when the key was last updated.

  • The date when the key was deleted.

Status Code

  • Created

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get resource key by ID

Get resource key by ID.

GET /resource_keys/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the key.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response
  • The ID associated with the key.

  • When you create a new key, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the key.

  • The full CRN (cloud resource name) associated with the key. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new key, a relative URL path is created identifying the location of the key.

  • The human-readable name of the key.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource instance or alias associated to the key.

  • The state of the key.

  • The credentials for the key. Additional key-value pairs are passed through from the resource brokers. Refer to service’s documentation for additional details.

  • Specifies whether the key’s credentials support IAM.

  • The relative path to the resource.

  • The date when the key was created.

  • The date when the key was last updated.

  • The date when the key was deleted.

Status Code

  • OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Delete a resource key by ID

Delete a resource key by ID.

DELETE /resource_keys/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the key.

Example request
curl -X DELETE \
  https://resource-controller.bluemix.net/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response

Status Code

  • Deleted

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The resource could was previously deleted and is no longer available.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This endpoint does not specify any sample responses.

Update a resource key

Update a resource key by ID.

PATCH /resource_keys/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the key.

  • The new name of the key.

    Example: my-new-key-name

Example request
curl -X PATCH \
  https://resource-controller.bluemix.net/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance-new-key-1",
  }'
Response
  • The ID associated with the key.

  • When you create a new key, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the key.

  • The full CRN (cloud resource name) associated with the key. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new key, a relative URL path is created identifying the location of the key.

  • The human-readable name of the key.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource instance or alias associated to the key.

  • The state of the key.

  • The credentials for the key. Additional key-value pairs are passed through from the resource brokers. Refer to service’s documentation for additional details.

  • Specifies whether the key’s credentials support IAM.

  • The relative path to the resource.

  • The date when the key was created.

  • The date when the key was last updated.

  • The date when the key was deleted.

Status Code

  • Successfully updated alias.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The request could not be processed.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get a list of all resource bindings

Get a list of all resource bindings.

GET /resource_bindings
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • The short ID of the binding.

  • The human-readable name of the binding.

  • Short ID of the resource group.

  • The unique ID of the offering (service name). This value is provided by and stored in the global catalog.

  • Short ID of the binding in the specific targeted environment, e.g. service_binding_id in a given IBM Cloud environment.

  • Limit on how many items should be returned

Example request
curl -X GET \
https://resource-controller.bluemix.net/v2/resource_bindings \
-H 'Authorization: Bearer <IAM_TOKEN>'
Response

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Create a new resource binding

Create a new resource binding.

POST /resource_bindings
Request

Custom Headers

  • Your IBM Cloud IAM access token.

  • The name of the binding.

    Example: my-binding

  • The short or long ID of resource alias.

    Example: 25eba2a9-beef-450b-82cf-f5ad5e36c6dd

  • The CRN of application to bind to in a specific environment, e.g. Dallas YP, CFEE instance

    Example: crn:v1:bluemix:public:bluemix:us-south:s/0ba4dba0-a120-4a1e-a124-5a249a904b76::cf-application:a1caa40b-2c24-4da8-8267-ac2c1a42ad0c

  • Configuration options represented as key-value pairs that are passed through to the target resource brokers.

  • The role name or it's CRN.

    Default: Manager

    Example: Manager

Example request
curl -X POST \
  https://resource-controller.bluemix.net/v2/resource_bindings \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance-binding-1",
    "source": "8d7af921-b136-4078-9666-081bd8470d94",
    "target": "crn:v1:staging:public:bluemix:eu-gb:s/f5038ca8-9d28-42a1-9e57-9b9fdd66bf8e::cf-application:b04ddee1-2838-449a-96d3-02a03179e991",
    "role": "Writer"
  }'
Response
  • The ID associated with the binding.

  • When you create a new binding, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the binding.

  • The full CRN (cloud resource name) associated with the binding. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new binding, a relative URL path is created identifying the location of the binding.

  • The human-readable name of the binding.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource alias associated to the binding.

  • The CRN of target resource, e.g. application, in a specific environment.

  • The short ID of the binding in specific targeted environment, e.g. service_binding_id in a given IBM Cloud environment.

  • The state of the binding.

  • The credentials for the binding. Additional key-value pairs are passed through from the resource brokers. Refer to the service’s documentation for additional details.

  • Specifies whether the binding’s credentials support IAM.

  • The relative path to the resource alias that this binding is associated with.

  • The date when the binding was created.

  • The date when the binding was last updated.

  • The date when the binding was deleted.

Status Code

  • Resource binding has been created

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get a resource binding

Retrieve a resource binding by ID.

GET /resource_bindings/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the binding.

Example request
curl -X GET \
https://resource-controller.bluemix.net/v2/resource_bindings/25b88996-c117-484a-a233-0db73e9177fa \
-H 'Authorization: Bearer <IAM_TOKEN>'
Response
  • The ID associated with the binding.

  • When you create a new binding, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the binding.

  • The full CRN (cloud resource name) associated with the binding. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new binding, a relative URL path is created identifying the location of the binding.

  • The human-readable name of the binding.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource alias associated to the binding.

  • The CRN of target resource, e.g. application, in a specific environment.

  • The short ID of the binding in specific targeted environment, e.g. service_binding_id in a given IBM Cloud environment.

  • The state of the binding.

  • The credentials for the binding. Additional key-value pairs are passed through from the resource brokers. Refer to the service’s documentation for additional details.

  • Specifies whether the binding’s credentials support IAM.

  • The relative path to the resource alias that this binding is associated with.

  • The date when the binding was created.

  • The date when the binding was last updated.

  • The date when the binding was deleted.

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Delete a resource binding

Delete a resource binding by ID

DELETE /resource_bindings/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the binding.

Example request
curl -X DELETE \
https://resource-controller.bluemix.net/v2/resource_bindings/25b88996-c117-484a-a233-0db73e9177fa \
-H 'Authorization: Bearer <IAM_TOKEN>'
Response

Status Code

  • Successfully deleted binding.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The resource could was previously deleted and is no longer available.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This endpoint does not specify any sample responses.

Update a resource binding

Update a resource binding by ID.

PATCH /resource_bindings/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the binding.

  • The new name of the binding.

    Example: my-new-binding-name

Example request
curl -X GET \
https://resource-controller.bluemix.net/v2/resource_bindings/25b88996-c117-484a-a233-0db73e9177fa \
-H 'Authorization: Bearer <IAM_TOKEN>'
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-instance-new-binding-1"
  }'
Response
  • The ID associated with the binding.

  • When you create a new binding, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the binding.

  • The full CRN (cloud resource name) associated with the binding. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you provision a new binding, a relative URL path is created identifying the location of the binding.

  • The human-readable name of the binding.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The CRN of resource alias associated to the binding.

  • The CRN of target resource, e.g. application, in a specific environment.

  • The short ID of the binding in specific targeted environment, e.g. service_binding_id in a given IBM Cloud environment.

  • The state of the binding.

  • The credentials for the binding. Additional key-value pairs are passed through from the resource brokers. Refer to the service’s documentation for additional details.

  • Specifies whether the binding’s credentials support IAM.

  • The relative path to the resource alias that this binding is associated with.

  • The date when the binding was created.

  • The date when the binding was last updated.

  • The date when the binding was deleted.

Status Code

  • Successfully updated alias.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The request could not be processed.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This endpoint does not specify any sample responses.

Get a list of all resource aliases

Get a list of all resource aliases.

GET /resource_aliases
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • Short ID of alias.

  • The human-readable name of the alias.

  • Resource instance short ID.

  • Short ID of the instance in a specific targeted environment. For example, service_instance_id in a given IBM Cloud environment.

  • The unique ID of the offering (service name). This value is provided by and stored in the global catalog.

  • Short ID of Resource group.

  • Limit on how many items should be returned.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_aliases \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response

Status Code

  • The alias was successfully retrieved.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Create a new resource alias

Alias a resource instance into a targeted environment's (name)space.

POST /resource_aliases
Request

Custom Headers

  • Your IBM Cloud IAM access token.

  • The name of the alias.

    Example: my-alias

  • The short or long ID of resource instance.

    Example: a8dff6d3-d287-4668-a81d-c87c55c2656d

  • The CRN of target name(space) in a specific environment, e.g. space in Dallas YP, CFEE instance etc.

    Example: crn:v1:staging:public:bluemix:us-south:o/5e939cd5-6377-4383-b9e0-9db22cd11753::cf-space:66c8b915-101a-406c-a784-e6636676e4f5

Example request
curl -X POST \
  https://resource-controller.bluemix.net/v2/resource_aliases \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance-alias-1",
    "source": "8d7af921-b136-4078-9666-081bd8470d94",
    "target": "crn:v1:staging:public:bluemix:eu-gb:o/e242c7f0-9eb7-4541-ad3e-b5f5a45a1498::cf-space:f5038ca8-9d28-42a1-9e57-9b9fdd66bf8e"
  }'
Response
  • The ID associated with the alias.

  • When you create a new alias, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the alias.

  • The full CRN (cloud resource name) associated with the alias. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new alias, a relative URL path is created identifying the location of the alias.

  • The human-readable name of the alias.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The CRN of target name(space) in specific environment.

  • The state of the alias.

  • The short ID of the resource instance that is being aliased.

  • The short ID of the instance in the specific target environment, e.g. service_instance_id in a given IBM Cloud environment.

  • The relative path to the instance.

  • The relative path to the resource bindings for the alias.

  • The relative path to the resource keys for the alias.

  • The date when the alias was created.

  • The date when the alias was last updated.

  • The date when the alias was deleted.

Status Code

  • Alias has been created.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Get a resource alias

Retrieve a resource alias by ID.

GET /resource_aliases/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the alias.

Example request
curl -X GET \
  https://resource-controller.bluemix.net/v2/resource_aliases/267bf377-7fa2-43f6-94ec-09103a8e89d4 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response
  • The ID associated with the alias.

  • When you create a new alias, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the alias.

  • The full CRN (cloud resource name) associated with the alias. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new alias, a relative URL path is created identifying the location of the alias.

  • The human-readable name of the alias.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The CRN of target name(space) in specific environment.

  • The state of the alias.

  • The short ID of the resource instance that is being aliased.

  • The short ID of the instance in the specific target environment, e.g. service_instance_id in a given IBM Cloud environment.

  • The relative path to the instance.

  • The relative path to the resource bindings for the alias.

  • The relative path to the resource keys for the alias.

  • The date when the alias was created.

  • The date when the alias was last updated.

  • The date when the alias was deleted.

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response

Delete a resource alias

Delete a resource alias by ID.

DELETE /resource_aliases/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the alias.

Example request
curl -X DELETE \
  https://resource-controller.bluemix.net/v2/resource_aliases/267bf377-7fa2-43f6-94ec-09103a8e89d4 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
Response

Status Code

  • Successfully deleted alias.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The resource could was previously deleted and is no longer available.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This endpoint does not specify any sample responses.

Update a resource alias

Update a resource alias by ID.

PATCH /resource_aliases/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the alias.

  • The new name of the alias.

    Example: my-new-alias-name

Example request
curl -X PATCH \
  https://resource-controller.bluemix.net/v2/resource_aliases/267bf377-7fa2-43f6-94ec-09103a8e89d4 \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance-new-alias-1"
  }'
Response
  • The ID associated with the alias.

  • When you create a new alias, a GUID (globally unique identifier) is assigned. This is a unique internal GUID managed by Resource controller that corresponds to the alias.

  • The full CRN (cloud resource name) associated with the alias. For more on this format, see https://console.bluemix.net/docs/overview/crn.html#crn.

  • When you created a new alias, a relative URL path is created identifying the location of the alias.

  • The human-readable name of the alias.

  • An alpha-numeric value identifying the account ID.

  • The short ID of the resource group.

  • The long ID (full CRN) of the resource group.

  • The CRN of target name(space) in specific environment.

  • The state of the alias.

  • The short ID of the resource instance that is being aliased.

  • The short ID of the instance in the specific target environment, e.g. service_instance_id in a given IBM Cloud environment.

  • The relative path to the instance.

  • The relative path to the resource bindings for the alias.

  • The relative path to the resource keys for the alias.

  • The date when the alias was created.

  • The date when the alias was last updated.

  • The date when the alias was deleted.

Status Code

  • Successfully updated alias.

  • The request could not be understood due to malformed syntax.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • The request could not be processed.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example Response