Querying the IBM Cloud Databases API from the Command Line

Querying the IBM Cloud Databases API from the Command Line

Querying APIs can look like a lot of complex and hard work at times. Sometimes the best way to explain things is to show, and in this article, we’re going to show the process of querying the API of the just-launched IBM Cloud Databases.

Your mission to query

Let’s approach this in a task-driven style: Our mission is that we want to get a list of backups for a deployment called RedFive.

First stop is consulting the API documentation for the backups endpoint. You’ll see it shows as /deployments/{id}/backups. That is just the path. The query needs to be sent to the appropriate API endpoint, which can vary by region. We call this the Foundation Endpoint. You can find that on the Manage screen in the IBM Cloud dashboard.

Grab that Foundation Endpoint. Now, let’s assemble a curl command using that information:

curl -s -X GET -H "Authorization: Bearer {apikey}" -H "Content-Type: application/json" \
"https://api.us-south.databases.cloud.ibm.com/v4/ibm/deployments/{id}/backups"

What we are missing here is an apikey and an id for the deployment.

Your API key

Your API key can be generated in the IBM Cloud IAM UI, but we’re going to assume that if you are curl-ing API requests, you’re probably more at home on the command line. Make sure you have the IBM Cloud CLI installed and you can create a dedicated key for your use. Then use the iam api-key-create command like this:

$ ibmcloud iam api-key-create ICDKEY -d "This is my ICD Key"

Creating API key ICDKEY as djwalkermorgan@uk.ibm.com...
OK
API key ICDKEY was created

Please preserve the API key! It cannot be retrieved after it's created.

Name ICDKEY
Description This is my ICD Key
Created At 2018-10-03T12:02+0000
API Key L12345678901234567890123456789012345678901234E
Locked false
UUID ApiKey-b58621f5-866f-4071-9366-368060c2abfd

Pay attention to that warning. Save the API Key somewhere safe. And to save us typing it again and again, let’s also put it in an environment variable, say CDBAPIKEY:

export CDBAPIKEY=L12345678901234567890123456789012345678901234E

Your service ID

Now to find your service. There’s the easy way—just look underneath the Foundation Endpoint in the IBM Cloud Databases overview. It’s labeled “Deployment ID.”

Or, you can look it up using the CLI. This time we can use the resource controller to do this. Here we find our RedFive instance:

$ ibmcloud resource service-instances --long
Retrieving service instances in resource group default and all location under account Dj Walker-Morgan's Account as djwalkermorgan@uk.ibm.com...
OK
ID

The output is somewhat wide, so we have wrapped it. What we want from this is the ID field.

Using the ID

Wherever you get the ID, it is in a CRN—a Cloud Resource Name.

The problem with CRNs comes when you use them in REST calls. They have a “/” in them and that will give you “not found” errors. You can replace the “/” with “%2F” manually or with a script.

In the latter case, here’s a way to translate CRNs to an always usable identifier:

python -c "import sys,urllib; print(urllib.quote(sys.argv[1],safe=''))" "YourCRNHere"

So, let’s apply that to our CRN and see:

$ python -c "import sys,urllib; print(urllib.quote(sys.argv[1],safe=''))" \
"crn:v1:bluemix:public:databases-for-redis:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8::"
crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-redis%3Aus-south%3Aa%2F54e8ffe85dcedf470db5b5ee6ac4a8d8%3A20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8%3A%3A

It actually escapes all the potentially tricky characters, even though the / is the problematic one.

But now we have our ID and it’s usable. Again, to save some typing lets put that into a OURCRN environment variable:

export OURCRN="crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-redis%3Aus-south%3Aa%2F54e8ffe85dcedf470db5b5ee6ac4a8d8%3A20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8%3A%3A"

Assembling our request

Taking our template from earlier and dropping in the apikey and deployment id, we get the following:

$ curl -s -X GET -H "Authorization: Bearer "$CDBAPIKEY -H "Content-Type: application/json" \
"https://api.us-south.databases.cloud.ibm.com/v4/ibm/deployments/"$OURCRN"/backups"

And if we run it, we see:

{"backups":[{"id":"crn:v1:bluemix:public:databases-for-redis:us-south:a/54e8ffe85dcedf470db5b5ee6
ac4a8d8:20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8:backup:0ed505bd-63d3-47cf-81d8-43344cc6c99e","deploym
ent_id":"crn:v1:bluemix:public:databases-for-redis:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:20c
946e1-1b9f-4ff9-85f0-33bcc7e3b2d8::","type":"scheduled","status":"completed","is_downloadable":fal
se,"is_restorable":true,"created_at":"2018-10-03T12:17:08.000Z"},{"id":"crn:v1:bluemix:public:data
bases-for-redis:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8:b
ackup:8ba7529a-08ce-443e-a6d8-d854c673625f","deployment_id":"crn:v1:bluemix:public:databases-for-r
edis:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8::","type":"s
cheduled","status":"completed","is_downloadable":false,"is_restorable":true,"created_at":"2018-10-
02T12:17:07.000Z"}]}

Not really that readable, but definitely a result.

Tip: Try the jq command to get well formatted JSON out of your curl command. Just add | jq to the end of the command.

Mission possible. One listing of backups obtained through the API.