Querying the IBM Cloud Databases API from the Command Line
5 min read
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:
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:
Please preserve the API key! It cannot be retrieved after it's created.
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:
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:
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:
So, let’s apply that to our CRN and see:
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:
Assembling our request
Taking our template from earlier and dropping in the apikey and deployment id, we get the following:
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.