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.cloud.ibm.com/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.cloud.ibm.com/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

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.

Response

A list of resource instances.

Status Code

  • The list of resource instances 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.

  • 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 responses

Create (provision) a new resource instance

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

POST /resource_instances
Request

Property values for the new resource instance.

Response

A resource instance.

Status Code

  • The resource instance was 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 responses

Get a resource instance

Retrieve a resource instance by ID.

GET /resource_instances/{id}
Request

Path Parameters

  • The short or long ID of the instance.

Response

A resource instance.

Status Code

  • The resource instance 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 responses

Delete a resource instance

Delete a resource instance by ID.

DELETE /resource_instances/{id}
Request

Path Parameters

  • The short or long ID of the instance.

Response

A resource instance.

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 method does not specify any sample responses.

Update a resource instance

Update a resource instance by ID.

PATCH /resource_instances/{id}
Request

Path Parameters

  • The short or long ID of the instance.

Updated property values for a resource instance.

Response

A resource instance.

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 responses

Get a list of resource keys

List all resource keys

GET /resource_keys
Request

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.

Response

A list of resource keys.

Status Code

  • The list of resource keys 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.

  • 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 responses

Create a new resource key

Create a new resource key.

POST /resource_keys
Request

Property values for the new resource key.

Response

A resource key.

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 responses

Get resource key by ID

Get resource key by ID.

GET /resource_keys/{id}
Request

Path Parameters

  • The short or long ID of the key.

Response

A resource key.

Status Code

  • The resource key 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 responses

Delete a resource key by ID

Delete a resource key by ID.

DELETE /resource_keys/{id}
Request

Path Parameters

  • The short or long ID of the key.

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 method does not specify any sample responses.

Update a resource key

Update a resource key by ID.

PATCH /resource_keys/{id}
Request

Path Parameters

  • The short or long ID of the key.

Updated property values for the resource key.

Response

A resource key.

Status Code

  • The resource key was successfully updated.

  • 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 responses

Get a list of all resource bindings

Get a list of all resource bindings.

GET /resource_bindings
Request

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

Response

A list of resource bindings.

Status Code

  • The list of resource bindings 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.

  • 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 responses

Create a new resource binding

Create a new resource binding.

POST /resource_bindings
Request

Property values for the new resource binding.

Response

A resource binding.

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 responses

Get a resource binding

Retrieve a resource binding by ID.

GET /resource_bindings/{id}
Request

Path Parameters

  • The short or long ID of the binding.

Response

A resource binding.

Status Code

  • The resource binding 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 responses

Delete a resource binding

Delete a resource binding by ID

DELETE /resource_bindings/{id}
Request

Path Parameters

  • The short or long ID of the binding.

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 method does not specify any sample responses.

Update a resource binding

Update a resource binding by ID.

PATCH /resource_bindings/{id}
Request

Path Parameters

  • The short or long ID of the binding.

Updated property values for the resource binding.

Response

A resource binding.

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 responses

Get a list of all resource aliases

Get a list of all resource aliases.

GET /resource_aliases
Request

Query Parameters

  • Short ID of the 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.

Response

A list of resource aliases.

Status Code

  • The list of aliases 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 responses

Create a new resource alias

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

POST /resource_aliases
Request

Property values for the new resource alias.

Response

A resource alias.

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 responses

Get a resource alias

Retrieve a resource alias by ID.

GET /resource_aliases/{id}
Request

Path Parameters

  • The short or long ID of the alias.

Response

A resource alias.

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 responses

Delete a resource alias

Delete a resource alias by ID.

DELETE /resource_aliases/{id}
Request

Path Parameters

  • The short or long ID of the alias.

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 method does not specify any sample responses.

Update a resource alias

Update a resource alias by ID.

PATCH /resource_aliases/{id}
Request

Path Parameters

  • The short or long ID of the alias.

Updated property values for a resource alias.

Response

A resource alias.

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 responses