Querying the IBM Cloud Databases API from the Command Line

Share this post:

Querying the API of IBM Cloud Databases

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" \

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
API key ICDKEY was created

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

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
GUID                                   Name                Location   
State    Type               Tags   Resource ID
20c946e1-1b9f-4ff9-85f0-33bcc7e3b2d8   RedFive             us-south   
active   service_instance          databases-for-redis

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=''))" \

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" \

And if we run it, we see:


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.

Compose's Technical Content Curator

More Databases stories
February 13, 2019

IBM Cloudant Security Update: TLS 1.2+ and Service Endpoints

The IBM Cloudant team wants to share some very important updates that will bring enhanced security to the service. These updates will change the way you engage with Cloudant, so please review to ensure that your applications can take advantage and continue uninterrupted.

Continue reading

February 13, 2019

Introducing IBM Cloudant Partition Queries: Faster, Cheaper, and More Scalable

To meet our customer demands while improving the scalability and performance of Cloudant, we are excited to introduce partition queries—a scalable, faster, and cheaper way to query a Cloudant database.

Continue reading

February 5, 2019

IBM Cloud Databases Update: New Regions and Integrations

We are excited to announce new integrations and the expansion of IBM Cloud Databases services into the IBM Cloud regions of Sydney, London, and Washington D.C.

Continue reading