Introduction

The IBM Cloud Databases API is a supplemental layer which adds the capability to manage IBM Cloud Databases through a REST API. The API is designed to provide users and developers the ability to examine their database deployments, upgrade deployments, manage users, manage connections, monitor tasks and work with backups.

An IBM Cloud Database is a cluster of nodes deployed using Kubernetes services. Such a configuration is referred to as a database deployment. The API does not manage provisioning or deprovisioning of the deployment; that is managed by the Resource Controller layer and API. The IBM Cloud Databases API can be used at any point after that in the database deployments lifecycle.

Authentication

Access to the API uses token authentication, using the header Authorization: Bearer <token>. The token must be IAM-issued. You can send in an IAM API key directly as the token or use the API key to generate an IAM Bearer Token.

Deployment IDs and CRNs

Deployment IDs are CRNs on the IBM Cloud Databases v4 API platform. When using a CRN, remember to URL encode the CRN value as it might include the forward-slash (/) %2F character. For example,

crn:v1:bluemix:public:databases-for-redis:us-south:a/274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7::

becomes

crn:v1:bluemix:public:databases-for-redis:us-south:a%2F274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7::

when URL encoded.

Error Handling

The IBM Cloud Databases API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 4xx type response is some sort of failure, and a 500 type response usually indicates an internal system error. Either of these responses may be accompanied by a JSON formatted body which contains more detailed error information.

Pagination

No endpoint currently returns paginated data.

Rate Limiting

No endpoint currently implements rate limiting.

This API does not support provisioning and decomissioning of database deployments. Those functions are the responsibility of the Resource Controller and the Resource Controller APIs.

Specifically the POST /resource_instances endpoint with appropriate resource_plan_id (such as databases_for_postgresql or databases_for_redis) can be used to create a new database instance. Consult the databases provisioning reference page for details of plan ids and other settings.

Methods

Get all deployable databases

Returns a list of all the types and associated major versions of database deployments that can be provisioned.

GET /deployables
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • A deployables object

  • Invalid token

Example responses

Get all deployable regions

Returns a list of all the regions that deployments can be provisioned into from the current region. Used to determine region availability for read-only replicas

GET /regions
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • A regions object

  • Invalid token

Example responses

Get deployment Information

Gets the full data associated with a deployment. This includes the id, name, database type and version.

GET /deployments/{id}
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A deployment response

  • Invalid token

No Sample Response

This method does not specify any sample responses.

Creates a database-level user

Creates a user in the database which can access the database through a connection.

POST /deployments/{id}/users
Request

Path Parameters

  • Deployment ID

Parameters for creating the user

Response

Status Code

  • A task which is being run to create the user

  • Invalid token

  • An error message response

Example responses

Set database-level user's password

Sets the password of a database-level user.

PATCH /deployments/{id}/users/{username}
Request

Path Parameters

  • Deployment ID

  • User ID

New Password Details

Response

Status Code

  • A task which is being run to set the user password

  • Invalid token

  • An error message response

Example responses

Deletes a database-level user

Removes a database-level user from the deployment.

DELETE /deployments/{id}/users/{username}
Request

Path Parameters

  • Deployment ID

  • User Name

Response

Status Code

  • A task which is being run to delete the user

  • Invalid token

  • An error message response

Example responses

Change your database configuration

Change your database configuration. Available for PostgreSQL ONLY.

PATCH /deployments/{id}/configuration
Request

Path Parameters

  • Deployment ID

Database configuration

Response

Status Code

  • A task

  • Invalid token

  • not found

Example responses

Get the schema of the database configuration

Get the schema of the database configuration. Available for PostgreSQL ONLY.

GET /deployments/{id}/configuration/schema
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A database configuration schema

  • Invalid token

  • not found

Example responses

Get read-only replica information

Get the read-only replica(s) associated with a deployment. Available for PostgreSQL ONLY.

GET /deployments/{id}/remotes
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A remotes object

  • Invalid token

  • not found

No Sample Response

This method does not specify any sample responses.

Modify read-only replication on a deployment

Promote a read-only remote replica to leader by calling with leader set to an empty string. Available for PostgreSQL ONLY.

PATCH /deployments/{id}/remotes
Request

Path Parameters

  • Deployment ID

Parameters for promoting a read-only replica

Response

Status Code

  • A task

  • Invalid token

  • not found

  • promotion is the only feature supported and must be requested as an empty string

Example responses

Resync read-only replica

Reinitialize a read-only replica. Available for PostgreSQL ONLY.

POST /deployments/{id}/remotes/resync
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A task

  • Invalid token

  • not found

Example responses

Get currently running tasks on a deployment

Obtain a list of tasks running or recently run on a deployment. Note that tasks are ephemeral and that completed or failed tasks may be removed from this list automatically and without warning.

GET /deployments/{id}/tasks
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • An array of tasks

  • Invalid token

No Sample Response

This method does not specify any sample responses.

Get information about a task

Get information about a task and its status. Tasks themselves are persistent so old tasks may be consulted as well as active/running tasks.

GET /tasks/{id}
Request

Path Parameters

  • Task ID

Response

Status Code

  • A task

  • A completed task redirects to the associated resource.

  • Invalid token

Example responses

Get information about a backup

Get information about a backup, such as creation date and including a link which may be followed to download the backup.

GET /backups/{backup_id}
Request

Path Parameters

  • Backup ID

Response

Status Code

  • A backup response

  • Invalid token

No Sample Response

This method does not specify any sample responses.

Get currently available backups from a deployment

Get details of all currently available backups from a deployment. Note that the backup entries do not include download links. These can be obtained by directly querying a backup for its details.

GET /deployments/{id}/backups
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • An array of backups

  • Invalid token

No Sample Response

This method does not specify any sample responses.

Initiate an on-demand backup

Signal the platform to create an on-demand backup for the specified deployment. The returned task can be polled to track progress of the backup as it takes place.

POST /deployments/{id}/backups
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A task

  • Invalid token

  • An error message response

Example responses

Discover connection information for a deployment for a user with an endpoint type.

Discover connection information for a deployment for a user with an endpoint type.

GET /deployments/{id}/users/{userid}/connections/{endpoint_type}
Request

Path Parameters

  • Deployment ID

  • User ID

  • Endpoint Type. Note that the select endpoint must be enabled on the deployment before its connection information can be fetched.

    Allowable values: [public,private]

Query Parameters

  • Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Response

Status Code

  • A Connection

  • Invalid token

Example responses

Discover connection information for a deployment for a user with substitutions and an endpoint type.

Discover connection information for a deployment for a user. Behaves the same as the GET method but substitutes the given password parameter into the returned connection information.

POST /deployments/{id}/users/{userid}/connections/{endpoint_type}
Request

Path Parameters

  • Deployment ID

  • User ID

  • Endpoint Type. Note that the select endpoint must be enabled on the deployment before its connection information can be fetched.

    Allowable values: [public,private]

Query Parameters

  • Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Optional parameters to be substituted into the response

Response

Status Code

  • A Connection

  • Invalid token

  • An error message response

Example responses

Discover connection information for a deployment for a user.

Discover connection information for a deployment for a user.

GET /deployments/{id}/users/{userid}/connections
Request

Path Parameters

  • Deployment ID

  • User ID

Query Parameters

  • Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Response

Status Code

  • A Connection

  • Invalid token

Example responses

Discover connection information for a deployment for a user with substitutions.

Discover connection information for a deployment for a user. Behaves the same as the GET method but substitutes the given password parameter into the returned connection information.

POST /deployments/{id}/users/{userid}/connections
Request

Path Parameters

  • Deployment ID

  • User ID

Query Parameters

  • Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Optional parameters to be substituted into the response

Response

Status Code

  • A Connection

  • Invalid token

  • An error message response

Example responses

Get currently available scaling groups from a deployment

Scaling groups represent the various resources allocated to a deployment. This command allows for the retrieval of all of the groups for a particular deployment.

GET /deployments/{id}/groups
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • An array of scaling groups

  • Invalid token

No Sample Response

This method does not specify any sample responses.

Get default scaling groups for a new deployment

Scaling groups represent the various resources allocated to a deployment. When a new deployment is created, there are a set of defaults for each database type. This endpoint allows you to retrieve them for a particular database.

GET /deployables/{type}/groups
Request

Path Parameters

  • Database type name

    Allowable values: [postgresql,etcd]

    Example: postgresql

Response

Status Code

  • An array of scaling groups

  • Invalid token

Example responses

Set scaling values on a specified group.

Set scaling value on a specified group. Can only be performed on is_adjustable=true groups. Values set are for the group as a whole and resources are distributed amongst the group. Values must be greater than or equal to the minimum size and must be a multiple of the step size.

PATCH /deployments/{id}/groups/{groupid}
Request

Path Parameters

  • Deployment ID

  • Group Id

Scaling group settings

Response

Status Code

  • A task which is being run to scale the deployment

  • Invalid token

  • An error message response

Example responses

Kill connections to a PostgreSQL deployment

Closes all the connections on a deployment. Available for PostgreSQL ONLY.

DELETE /deployments/{id}/management/database_connections
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A task

  • Invalid token

  • not found

Example responses

Retrieve the whitelisted addresses and ranges for a deployment.

Retrieve the whitelisted addresses and ranges for a deployment.

GET /deployments/{id}/whitelists/ip_addresses
Request

Path Parameters

  • Deployment ID

Response

Status Code

  • A Whitelist

  • Invalid token

  • An error message response

Example responses

Replace the whitelist for a deployment.

Replace the whitelist for a deployment. Note that this will overwrite all existing entries, so when modifying the whitelist via a GET/update/PUT, provide the GET response's ETag header value in this endpoint's If-Match header to ensure that changes made by other clients are not accidentally overwritten.

PUT /deployments/{id}/whitelists/ip_addresses
Request

Custom Headers

  • Verify that the current whitelist matches a provided ETag value. Use in conjunction with the GET operation's ETag header to ensure synchronicity between clients.

Path Parameters

  • Deployment ID

New Whitelist

Response

Status Code

  • A task which is being run to add the whitelist entry

  • Invalid token

  • An error message response

Example responses

Add an address or range to the whitelist for a deployment.

Add an address or range to the whitelist for a deployment.

POST /deployments/{id}/whitelists/ip_addresses
Request

Path Parameters

  • Deployment ID

New Whitelist Entry

Response

Status Code

  • A task which is being run to add the whitelist entry

  • Invalid token

  • An error message response

Example responses

Delete an address or range from the whitelist of a deployment.

Delete an address or range from the whitelist of a deployment.

DELETE /deployments/{id}/whitelists/ip_addresses/{ipaddress}
Request

Path Parameters

  • Deployment ID

  • An IPv4 or IPv6 address or a CIDR range (netmasked IPv4 address)

Response

Status Code

  • A task which is being run to delete the whitelist entry

  • Invalid token

  • An error message response

Example responses