Getting Started with the API
This topic explains how to get started with the use of the Agility APIs.
Overview
The API facilitates integration with external systems and allows direct queries to the Digital.ai Agility data. This list contains some pointers for those getting started with the API.
Common Assets & Translations
The API uses the database name of each asset. Here are a few common assets that are helpful to know when you create your queries:
| API Name | Application UI Name |
|---|---|
| Scope | Project |
| Timebox | Iteration or Sprint |
| Story | Story, Backlog Item, or Requirement |
| Actual | Effort or Done |
Know that you can always query the localization API to determine if an API name has a translated UI name in your system. Because the UI labels can be customized, the application UI name in your own system can differ from the common set above.
List of Assets and Attributes
Query the meta API to get a list of all the assets in the system as well as the attributes and relations of each. Use the following query to apply xsl which formats the list for easier viewing.
<Server Base URI>/meta.v1?xsl=api.xsl
Replace the <v1-server> and <v1-app-name> tags in the above with your specific system information.
Alternatively, you could get all the attributes and relations of a single asset by adding that asset name to the query, for example:
<Server Base URI>/meta.v1/Story?xsl=api.xsl
Asset States
Asset State is used to define the system-known Agility for an asset. The UI, for example, will typically query assets that are not = 'Dead' to automatically exclude those items from the return results.
0 => Future
64 => Active
128 => Closed
200 => Template (Dead)
208 => Broken Down (Dead)
255 => Deleted (Dead)
Formatting Output
Use xsl to format the output of API queries. A couple of xsl files have been created to format output in popular ways.
- Table View (table.xsl)- see results as an easily-readable report with values in columns
- Story Card View (storyCards.xsl ) - format and print out story cards from your backlog
- Epic Card View (epicCards.xsl) - Format and print out epic cards with ID, Name, Owner, and Team
If you want these loaded to your hosted instance, please send an email to support@digital.ai and make sure to mention your instance URL and which XSL you want loaded. We will install them in the /custom folder.
On-Premises (local) installations
Right-click the links below to download and save the files locally:
To use them in your system, you will need to install the xsl files in a /custom directory on your web server under the VersionOne application. However, to actually access the cards and use the storycards, you need to run a query similar to this:
<Server Base URI>/rest-1.v1/Data/Story?Where=Scope.Name="ProjectName"&xsl=custom/storyCards.xsl
Make sure there is no slash in front of "custom". To make changes to the storycards xsl file, you will need to have a bit of API knowledge. If you require assistance, please contact Support and discuss a Services engagement for assistance.
On-Demand (Hosted) customers
To request these.xsl files, contact Digital.ai Support.
For example, to turn this API query:
<Server Base URI>/rest-1.v1/Data/Story?select=Name,Description
...on a hosted system into one that outputs the contents in tabular format, you can specify using the table.xsl by referencing it's location in /custom/table.xsl like so:
<Server Base URI>/rest-1.v1/Data/Story?select=Name,Description&xsl=custom/table.xsl
Additional Help for REST API Queries
There is built in API specific Help available on your instance.
<Server Base URI>/help/api/rest-1.html
This Help feature shows examples of code and queries and syntax that should assist you in getting your own API code up and running.