The IBM Cloud Compose API

Published

A version of the Compose API is available for IBM Cloud Compose users. This document covers how to access the API, what API endpoints are available and how to translate the Compose API to the IBM Cloud Compose API.

What you'll need

To make use of the API, you will need a handful of digital assets; a token for your IBM Cloud API and the name of an existing IBM Cloud Compose database deployment.

API Tokens

To use the API you will need an IBM Cloud API Token. This can be created from the IBM Cloud Dashboard by selecting ManageSecurityIBM Cloud API Keys and generating a key on the Platform API Keys page.

An existing database deployment

Each deployed database is situated in an IBM Cloud region and has a service instance id. All IBM Cloud Compose API calls require a service instance id for a deployed database to be performed. Presenting this service instance ID gives a context to the API request.

To obtain the service instance ID for a database, consult the deployment name, displayed in the Deployment Details. For example, if the deployment name is displayed as this:

Deployment Details

Then our service name is this:

bmix-lon-yp-1988a8e6-136a-4a3a-a049-d2eae7ed1ccf

Our service instance id is everything after the third - giving us this: 1988a8e6-136a-4a3a-a049-d2eae7ed1ccf

If you use the IBM Cloud cli, you can also obtain the service instance ID by logging in (bx login), targetting the appropriate organization and space (bx target -o org -s space) and querying the service with bx cf service --guid SERVICENAME.

Regions and endpoints

The API call must also be performed on the endpoint in the same region as the deployed database. The IBM Cloud user interface shows the current region in the top right when examining the database. If you have the deployment's name though, you can determine the region using the prefix to the service instance ID. Consult the table below to obtain appropriate endpoints be region or prefix.

API Endpoints by region and prefix

RegionName PrefixAPI Endpoint
US South
Dallas
us-south
bmix-dalhttps://composebroker-dashboard-public.mybluemix.net
United Kingdom
London
eu-gb
bmix-lonhttps://composebroker-dashboard-public.eu-gb.mybluemix.net
Germany
eu-de
bmix-eudehttps://composebroker-dashboard-public.eu-de.mybluemix.net
Sydney
au-syd
bmix-sydhttps://composebroker-dashboard-public.au-syd.mybluemix.net

With our example deployment, this gives us London as the region and https://composebroker-dashboard-public.eu-gb.mybluemix.net as the API endpoint.

Using the API

Getting the deployment id

At this point, you should have an IBM Cloud API key, a service instance id and an endpoint. This can be used to create an endpoint to query for the deployment ID associated with the service instance. The deployment ID is the compose identifier used within API calls and is needed for queries that reference the deployment.

The deployment ID endpoint is comprised of the API endpoint with /api/2016-07/instances/ and the service instance ID appended. In our example, this would give us

https://composebroker-dashboard-public.eu-gb.mybluemix.net/api/2016-07/instances/1988a8e6-136a-4a3a-a049-d2eae7ed1ccf  

We will call this the database's foundation endpoint. It can be queried directly to obtain a deployment ID with no other parameters. As an example, let's compose a cURL command to query for the deployment id. The IBM Cloud API key should be included as an authorization header - here it is available in an environmental variable $IBM_CLOUD_API_TOKEN:

$ curl -s -X GET -H 'authorization: Bearer '$IBM_CLOUD_API_TOKEN -H 'content-type: application/json' https://composebroker-dashboard-public.eu-gb.mybluemix.net/api/2016-07/instances/1988a8e6-136a-4a3a-a049-d2eae7ed1ccf 
{"id":"1988a8e6-136a-4a3a-a049-d2eae7ed1ccf","resource_type":"deployment","resource_id":"59e731d3cc3d1c0024b356e7"}
$

This returns a JSON document which contains the service instance ID, resource type, and resource id. If we format the returned data with jq we get this.

{
  "id": "1988a8e6-136a-4a3a-a049-d2eae7ed1ccf",
  "resource_type": "deployment",
  "resource_id": "59e731d3cc3d1c0024b356e7"
}

The resource_id is our deployment ID.

Querying the database deployment

The Compose API has an endpoint to get details for a deployment which is the GET /deployments/:id endpoint. This query takes a deployment ID as a path parameter. We can drop the 2016-07 from the Compose API endpoint leaving /deployments/:id to append to our foundation endpoint. This creates an endpoint to get details of the IBM Cloud Compose deployment.

In our example, this would give us an endpoint of https://composebroker-dashboard-public.eu-gb.mybluemix.net/api/2016-07/instances/1988a8e6-136a-4a3a-a049-d2eae7ed1ccf/deployments/59e731d3cc3d1c0024b356e7. If we query it, we get returned the data as specified in the Compose API page

$ curl -s -X GET -H 'authorization: Bearer '$IBM_CLOUD_API_TOKEN -H 'content-type: application/json' https://composebroker-dashboard-public.eu-gb.mybluemix.net/api/2016-07/instances/1988a8e6-136a-4a3a-a049-d2eae7ed1ccf/deployments/59e731d3cc3d1c0024b356e7 | jq

returns

{
  "id": "59e731d3cc3d1c0024b356e7",
  "account_id": "57e556a3242d4e0014b553fc",
  "name": "bmix-lon-yp-1988a8e6-136a-4a3a-a049-d2eae7ed1ccf",
  "type": "etcd",
  "created_at": "2017-10-18T10:49:55.528Z",
  "notes": "",
  "customer_billing_code": "",
  "cluster_id": "57d6dfd69967020016001fad",
  "ca_certificate_base64": "OMITTED",
  "connection_strings": {
    "direct": [
      "https://root:PASSWORD@bluemix-sandbox-dal-9-portal.2.dblayer.com:30119",
      "https://root:PASSWORD@bluemix-sandbox-dal-9-portal.3.dblayer.com:30119"
    ],
    "cli": [
      "ETCDCTL_API=3 etcdctl --endpoints=https://bluemix-sandbox-dal-9-portal.2.dblayer.com:30119,https://bluemix-sandbox-dal-9-portal.3.dblayer.com:30119 --user=root:PASSWORD member list -w table"
    ],
    "maps": [],
    "misc": {},
    "ssh": [],
    "health": [],
    "admin": []
  },
  "version": "3.2.7"
}`

Available API calls

Using the method outlined above, the following Compose API calls are supported.

Deployment related

General