Working with the VersionOne API
In this previous piece, I covered the basics of getting started with the VersionOne (V1) API, providing useful links for reference information and additional learning as well as an example of using the V1 API Console to run a simple query. I also described some shortcomings of the V1 API Console and promised to offer a better way. This piece will describe how to use Postman (a popular API Development Environment/REST Client) to provide a better development experience. [If you prefer a different client (like Insomnia), the instructions here should give you the information you need to set it up, with a little extra work on your part.]
One thing this won’t be is a Postman tutorial. The official docs are good and include a collection of video tutorials as well. That said, you should be able to follow the steps here and be successful with Postman even if you are new to it (though you’ll need the docs to install it, I assume you have)— there’s just more to know and it’s worth knowing. As a reader who is continuing, I presume you have read the previous piece linked above, are not afraid of using a REST client, and want to learn a bit more about using the V1 Query API.
You have installed Postman, right? Or at least some other useful API Client and are prepared to work it out? Because the rest of this won’t be much fun if you are only reading and not working along with me. Let’s go.
Heads-up: I’m going to use a few optional aspects of Postman that I think are useful and will make for a better experience if this is something you continue to use. We’ll create a Collection for the V1 queries so we can save them, reuse them and share them easily. We’ll configure the API Key we’ll retrieve from V1 in the next step as a Variable and store it once in the Collection from where the queries in the Collection can inherit it. If you share your Collection, you DO NOT want to share your API key and storing it once in a Variable makes it easy for folks you share it with to add their own key as the value for the Variable just once and then all of the queries should work (using their own credentials, not yours).
Perhaps the only advantage of the V1 API Console is that it’s browser-based and as long as you can log into V1, the Console will work, using the credentials your browser already has. To use any sort of other client (be it Postman or a custom application), you’ll need to create a V1 API Key that you’ll pass in as your credentials. This section describes how to get that key (be sure to save it somewhere safe as it cannot be retrieved from V1 later). It is easy to make keys, so if you lose it (or accidentally publish it and need to quickly delete it), you can make another. Again, storing the key in a Variable will make it easier to replace.
Because there are multiple versions of V1, the screen captures used may not exactly match what you’ll see — apologies for that and I’m sure you can figure it out.
You need to go to your V1 Applications page to create a key. This should be available from your personal avatar, typically in the upper right of the page:
This link should take you directly to your Applications section of your Member page. If you go to your Member page some other way, use the Applications link to switch to the Applications section.
You need to give the “application” a name. Since it’s not really an application (I was never tempted to type “Postman” into that box), I suggest using a name that reminds you what you made the key for (in this case, “V1APIDemo”). I am not enough of a VersionOne expert to understand the implications of creating a public key for anyone to use, so I create a personal key and expect those using the solution to do the same. [If this API thing I’m working on takes off, I may have to figure that out and I promise to come back here and update with better advice if I have it.]
Click Add and you’ll get a popup with your key text. Copy this somewhere safe, you’ll need it later.
You will then see an “application” with the name you entered in your list of Personal Applications. If you no longer need a key or think the key may have escaped your personal control, you should come back here and use the action to Revoke the key so that no one else can use it.
Now that we have the key, we’ll spend the rest of our time in Postman building our queries.
Postman
We’ll start by creating our Collection, then adding our API key to it (so all of our queries can inherit it) via a Variable (so that someone using our Collection can add their own API key into the same variable name and, voilà, everything in the Collection will work for them). Then we’ll finally get to writing some queries.
For the Postman parts, I’m using it without logging in (that way you creating a Postman account doesn’t become a prerequisite because I took advantage of something that may only work for logged in users).
In the New Collection dialog, we’ll enter data in several different sections. Start by entering a name for the Collection and perhaps a description. Do not click Create yet as we’re not done.
Next we’ll go to the Variables section and create a variable for our API key.
You’d think the next thing would be to use the Authorization section to actually configure our API key for use with our calls. But that won’t work. Even though we made the Variable and assigned the API Key to it, Postman doesn’t think it exists, I’m guessing because we didn’t save the Collection yet. So we’ll need to create the collection, then edit it to add the Authorization info). So click Create near the bottom of the dialog, then I’ll walk through editing it to add the Authorization information. You’ll need to know how to edit anyway, so a useful detour.
Whoa, wait a second, what happened? If you just see the Postman application page without your Collection visible, you’ll need to open the Sidebar in order to see the list of Collections. Use the View → Toggle Sidebar menu or the Sidebar toggle button (in the lower left corner) to open the sidebar.
A couple things to notice before we charge on. The star next to the collection name, when “on” causes the collection to sort to the top of the list (which is alphabetically sorted, otherwise). As you add collections, that can be helpful. The “…” link will bring up the menu (partially) shown. The “>” above that will pop out a panel with summary info about the collection (and an icon ribbon that is the same actions as this menu).
Click Edit to get things going again. This will bring the Collection dialog up again. Go to the Authorization section. Choose Bearer Token as the type of authorization to use.
Rather than copy in your token (see “Heads up!” about sensitive data), we’ll use the “handlebars” substitution notation to tell Postman it should get the Variable’s value and use it here.
A mild bit of sadness here: The variable text appearing in red means it can’t find it (or doesn’t think it can). When this works as it should, entering the first ‘{‘ will get you a list of possible variables. That’s not the experience I’ve been getting, though. It does resolve itself eventually (or I wouldn’t be writing this) but it’s a bit disappointing that it isn’t already just working. Even this detour doesn’t fix it, yet it still all works in the end.
Click Update for the Collection. When you click on your Collection in the sidebar, you’ll see a prompt to create a request to add to the Collection.
Go ahead, click the link and let’s add our first query (we’ll use the same one we created in the first article). Since we clicked the link to add a Request from our Collection, the Collection name is already populated for us.
Add a descriptive name, an optional description and verify that the “OK” button is saving to the correct Collection (then click it). You’ll see your new request as part of the sidebar. Click it to open it in the editor.
Similar to the V1 API Console, we need to switch to POST and change the payload type to accept our YAML code (the “raw” choice), add our query.v1 endpoint — but in this case we need to prepend the <Server Base URI>/ and enter our query in the body panel.
Click Send (feel free to click Save as well to save your changes to the Request into the Collection).
In addition to the response, you can also see how long it took and the overall size of the data returned.
Oddly (and thankfully), the weird issue with the API key variable (remember that note above?) just worked itself out somewhere along the way (if you look in the Headers for the request you’ll see that it created the correct Authorization head and populated the key from the Variable in our Collection).
So, what next? Let’s add another query to our Collection. Someone recently said We need to make sure all Features have a non-blank Status. Let’s add a query that will give us that list.
The easiest way to add a Request to our Collection is to duplicate a working one.
I’ll dispense with all of the screenshots this time. Name the new request Features without Status. Here’s the new query for the payload (remember to include the page: command to avoid unnecessarily large result sets):
Aside: For the database-oriented reader, that may look weird. How can I get the Name from a Status object when there isn’t actually a Status object related to the Epic yet? And use it in a where clause, to boot? Insanity — but it works (the V1 query engine is clearly lending a helping hand behind the scenes). You can test this out by changing the where clause to Status.ID: NULL. You’ll get the same result set.
So now you have two queries in the collection. I’ll leave it to you to expand and improve on that as needed. One likely improvement is that if you have an enterprise instance of V1, you’ll likely want to qualify most queries with at least a Scope (Project/Release) and a Team Name (unless you have the unhappy job of fixing everyone’s work items for them).
Here’s a peek at how I’ve done that sort of thing to make it more easily shared, safer and explicit.
Using the with: command, you can specify variables and their values (where have we seen that before…). Using the matching name, e.g., $status, the query engine will lift the value from with: and replace it wherever it sees the variable mentioned. Note that if your string has unfortunate characters (in this case, though you can’t see them, colons and ampersands), you can put quotes around the string to keep the YAML interpreter from choking.
Why do this? Can’t we just put the value in the where clause? You could. In my experience, it’s safer to separate the part people will edit for “configuration” from the “code” that does the work. In this case, it also makes it explicit which parts of the query are meant to be customized.
What’s next? Digging through the various doc links (mostly in the previous post) is likely crucial to long-term success. Learning more Postman (or your client of choice) won’t hurt. And talk to your team — what queries can you create that will make y’all more successful?
For me, I’m going to continue the journey of turning this into a dashboard, building up a collection of queries that provide a list of links to be clicked and fixed. I’ll share those details (likely a node.js service in a container with a simple Vue.js UI) when they are ready. Follow me for a notification.
