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 account to access the IBM Cloud API and a foundation endpoint for your queries.

sidenote-right Shortcuts:
Available API calls
Appendices:
Deriving endpoints from deployment names
Getting a deployment id

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.

The foundation endpoint

For any database deployment, there is a foundation endpoint. This is based on the IBM Cloud region the database is situated in and the service instance id that database has. There are a number of ways of obtaining this endpoint.

Using the IBM Cloud Console

Within the IBM Cloud Console for a deployment is a panel marked Instance Administration API. This panel carries the complete foundation endpoint.

Instance Administration API Panel

The same panel also contains the deployment ID. This is also needed when composing many, if not most, API request. Make a note of it.

Using the VCAP

If your application runs on the IBM Cloud platform, it will be bound to the database service. The credentials for the service will be passed as part of the VCAP environmental variable and parsing that will reveal a property called instance_administration_api. Within this property, you will find root endpoint and an instance_id.

You can turn this into a foundation endpoint by appending /api/2016-07/instances/ to the root endpoint and then appending the instance id to that. Note that the "2016-07" represents the current version of the API, "2016-07", as of writing.

The instance_administration_api also includes the deployment_id which will be needed to compose API request.

Using the API

Querying the database deployment

We start with the foundation endpoint. This is our example foundation endpoint:

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

If we consult the Compose API documentation, we find it has an endpoint to get details for a deployment which is the GET /2016-07/deployments/:id endpoint. This endpoint takes a deployment ID as a path parameter.

To compose our API request, we remove the API version from the /2016-07/deployments/:id endpoint and append the result to our foundation endpoint. Then we replace the :id with our deployment id.

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

This is now a complete endpoint for getting details of this specific IBM Cloud Compose deployment.

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


Appendix 1

Deriving endpoints from the deployment name

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. Both the region and the service instance ID go into creating what we call the foundation endpoint. This is a URL which you use to prefix Compose API

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 PrefixRoot Endpoint
US South
Dallas
us-south
bmix-dalhttps://composebroker-dashboard-public.mybluemix.net/api
United Kingdom
London
eu-gb
bmix-lonhttps://composebroker-dashboard-public.eu-gb.mybluemix.net/api
Germany
eu-de
bmix-eudehttps://composebroker-dashboard-public.eu-de.mybluemix.net/api
Sydney
au-syd
bmix-sydhttps://composebroker-dashboard-public.au-syd.mybluemix.net/api

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

Composing your foundation endpoint

You should have a root endpoint and a service instance id. These can be used to create a foundation endpoint which we will use for all API calls.

The deployment ID endpoint is comprised of the API endpoint with /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 can now use this foundation endpoint to create new API queries.


Appendix 2

Getting a deployment id

The first thing you can do with the foundation endpoint is query it directly to obtain a deployment ID. The deployment ID is an internal Compose id which is a unique ID for the database. While the service instance id authorizes your query to get this information, the deployment id is used within various API calls as a parameter.

Note, if you are using the VCAP method, you will find the deployment id as an extra field in the instance_managament_api date. On the console overview, the deployment id is available, embedded within an example API call for deployment details.

This technique is therefore only needed if you have no available deployment id and need to establish it programatically.

We'll 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.