This is a bit of a case study in the day-to-day work of a software engineer, tied in to a tech tip for OpenStack.  I’m going to throw a few footnotes at the end, so if a term doesn’t make sense bear with the story and I’ll explain it at the end. 😉

In my day job, we are building foundational services for provisioning of servers, networks, and other resources.  We already have a slick platform for this, but are always improving it.  This week as we were working on a recovery story and needed a way to find out if a particular volume had been created, we wanted to query Cinder for some matching metadata.  While we knew it was possible, none of us was sure of the syntax.  So we went to googling for some documentation.  But our searches for “query parameters” to OpenStack Cinder were frustrated.  So we tried looking into the source code for Cinder – its open source and Python, so it is all on github and mostly readable.  That led to some slightly obfuscated code that led us to believe there are filters that can be used.  More googling for “filters” and “search parameters” led to the command line tool for Cinder.

With the proper environment variables in place, the Cinder command line tool works like this:
cinder list –metadata mykey=myvalue1

Getting closer. But we want to use the REST API.  So on to experimentation.  We knew from the limited docs and source code that the volumes URL was what we wanted.

So to try it out, I wrote a quick bash script to invoke curl with the parameters we needed, including the Keystone token. We quickly determined that the JSON metadata query (which can be a partial match to the metadata stored for the volume) needed to be

URL encoded.  Another quick Google and we had an interactive URL encoder up in a browser to run our test JSON string through ten cut and paste into the bash curl script.
But something was still not right. Finally it dawned on me.  When I first wrote the curl command, I wrote it like
http://localhost:8776/v2/{tenantid}/volumes

And naturally when I wanted to query I slapped a / on the end then the query parameters, like

http://localhost:8776/v2/{tenantid}/volumes/?metadata=%7B%22blah%22=%22blah%22%7D

Anyone spot where I went wrong? ‘volumes’ is a resource, not a path, so that slash is sending the request off to nowhere.

Take out the slash.

http://localhost:8776/v2/{tenantid}/volumes?metadata=%7B%22blah%22=%22blah%22%7D

Took longer than it should have, and could have been avoided with a few lines of documentation.

While there is a lot of OpenStack documentation out there, the little technical details can be hard to find.  And this was a case where just getting the right key words into Google wasn’t enough.

OpenStack Cinder is a block storage service used to allocate chunks of hard drive space as virtual volumes for use by virtual machines or attached as external storage to real bare metal servers.
JSON is a markup language like XML but much terser and easier on the whitespace.  I rather like it as long as you have a checker handy to catch missing commas.
Bash is a common shell scripting language.  cURL is a command line toll for sending a request to a URL, which is really handy for repeatedly testing a REST API.  REST APIs are a pattern for remote calls to a server, and I’ll say that the wikipedia article for REST has many more technical words than I want to type out on my 7 inch tablet. 😉

One more reference if you are looking for Cinder documentation.
developer.openstack.org/api-ref-blockstorage-v2.html