This post is from the Collabnet VersionOne blog and has not been updated since the original publish date.
There’s an API for That… How to Get Lots of Information in a Few Moments
A few days ago, I was using my smartphone and wanted to get some more information about the weather besides just the basics of temperature and local conditions i.e. sunny, cloudy and such. I was reminded of the contemporary colloquialism “There’s an APP for that” so I browsed in the online store and sure enough there were plenty of them offering such things as air speed, barometers, wind direction, moon phase, etc., etc. After choosing one, I downloaded it and it was simple to setup providing a whole lot more information in a few moments. And now, it’s available whenever I need it. I’m surprised that I didn’t set this up years ago. Along those same lines… VersionOne has an API (Application Programming Interface), which can give lots of information in a few moments as well. Yes, it is powerful so this might sound strange that it’s really easy to use. I’ll say it this way…if you can type a URL, you can use the VersionOne API. This is done in the form of a query and returns a set of data for the answer. NO CODE needed. Why would you want to use the API instead of reports? Good question. Just like the regular regional weather forecast, there are many good standard reports ready to run inline embedded in VersionOne or in the general “reports” area. Still, there are times when it helps to have a more detailed version of the weather by selecting options like air speed, barometers, wind direction, or moon phase. In similar fashion, entering different parameters with the API can produce more targeted data than what is available in the report specification. Using the API allows this to happen easily and quickly. Example 1 - The Data API The first place to start is with the Data API, which provides access to the production database. Go to your favorite Browser and login to your instance of VersionOne. Once signed in, queries can be run without having to put security credentials in again. Also, keep in mind that the queries will be limited to the current role, project access, etc. Once logged in, copy the Base URL from the Browser address bar for the VersionOne instance. Example: https://www8.v1host.com/(your instance) ***Be aware that if you are typing a URL, it is case sensitive. Open a new tab in the browser and paste the Base URL in…then add: /rest-1.v1/Data/Epic and press the “Enter” key to run your query. This will give you a list of ALL the epics in your instance with direct access to the production database. They are listed as a group of assets in XML format with attribute information, etc. The total attribute shows how many were found such as total=40 in the example. The word epic is the parameter and can be substituted for any asset such as story, defect, task or test. Remember this query returns ALL Epics so it may take a while to run and it could become a performance drag on the production database. For this reason, the query should always be filtered for smaller and faster results. Let’s add another parameter as a filter to the query to reduce the size of the answer. In the set of information returned, there are attributes and relations. One of the relations is scope, which is the project or planning level in VersionOne. This can be used in the query to limit the result to only one project or planning level. Add the following to the query in the address bar: ?where=Scope.Name=’Your Project Name’ and make sure to change the parameter to your project name. This is the “where” keyword which facilitates adding parameters to the query. To add additional parameters, use a “;” between each one on the address bar. Hit enter and watch the results. Look at the total again…it should be lower and the query will run faster. Example 2 – The Meta API There are also many attributes in the epic itself, some of which may not have been seen before. These attributes can be viewed as part of the Meta API. For the next example, let’s look at the attributes of an epic a little bit closer. Open a new tab in the browser and paste the same base URL from above in…then add: meta.v1/Epic?xsl=api.xsl and press the “enter” key to run your query. The “xsl=api.xsl” portion helps to format the result making it easier to read. The new view is showing the Metadata for the Epic including attributes and operations. This type of query gives a complete view of the data available for each type of asset. Again, changing the “epic” keyword in the query to story, task, etc. will show their metadata. The red asterisk indicates the “required” attributes, which must have data in them. The rest of the attributes are optional but available for data input by the user or the system. Example 3 – Selecting Attributes There are also many attributes in the epic itself, some of which may not have been seen before. For the next example, create another query with just a few attributes. Go back to the tab in the browser with the address using the data API and add: &sel=Name,Scope.Name and press the “enter” key to run the query. The updated view still only shows the epics in the scope of the where keyword but now just with the name and scope attributes selected. Adding the “&” allows both the “where” and “sel” parameters in one query. Summary Just like in the real world when you need some more information and there is an App for it, you now know there is an API for querying information from VersionOne. There are many other things that can be done with the API and plenty of documentation for it located on the VersionOne Developer Library. The main thing is to get started and see all the information waiting for you in just a few moments. It just might turn your day from cloudy to sunny very quickly.