The API helps to facilitate integration with external systems and allows direct queries to the VersionOne data. This list contains some pointers for those getting started with the API.
API Overview
See the Platform of this site for more information on the API.
API Help
Help is available online in your VersionOne system. See the online Help topic Miscellaneous > API for details. There are three portions of the Help:
- Data API - examples of how to create API calls
- Meta API - lists the attributes and relations for each one of the assets available through the API
- Localization API -helps you find the UI label used for the different database terms used in the application
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.
http://<v1-server>/<v1-app-name>/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:
http://<v1-server>/<v1-app-name>/meta.v1/Story?xsl=api.xsl
Asset States
AssetState is used to define the system-known lifecycle 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.
On-Premise (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. See the discussion post links at the right for more information.
On-Demand (hosted) customers
You automatically have access to both of these .xsl files. For example, to turn this api query:
http://www1.v1host.com/MyCompany/rest-1.v1/Data/Story?sel=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 s/custom/table.xsl like so:
http://www1.v1host.com/MyCompany/rest-1.v1/Data/Story?sel=Name,Description&xsl=/s/custom/table.xsl
