This is the first in a series of technical articles about the VersionOne API. The goal of this series is to help the reader better understand the VersionOne open platform.
The VersionOne application supports a robust RESTful API that is available on all installations regardless of license. REST is an acronym for REpresentational State Transfer, a proven and commonly used web services architecture based on HTTP & XML. Unlike SOAP, a RESTful API does not require an intermediate messaging layer, resulting in a simpler approach with superior performance. Since there are no cross-platform implementation issues or complexities, you can access this API using any programming language or directly from your web browser. VersionOne offers client side libraries in C# and Java to make application development easier, but in this article I will use URLs so you can experience the power of our API using your favorite web browser.
The first important thing to know when using the API is that the interface does not refer to assets using the same terminology as the UI. The best example of this is the ‘Project’ asset, which is referred to as ‘Scope’ when accessed through the API. The secret decoder ring for all asset types is located in the ‘‘Data API’’ section on the Core API page mentioned in the reference section of this article.
The second important thing to know is that our API is really comprised of 3 interfaces:
- A Data API which allows you to create, retrieve, and manipulate information in the application.
- A Meta API which allows you to discover information about the asset types and attributes available through the Data API.
- A Localization API which allows you to retrieve the localized value for a specific term. For example you could use this API to discover that ‘Story’ is called ‘Backlog Item’ when using the SCRUM template.
Finally, here are some basic attributes that all asset types share:
- Name – the name of the asset.
- Description – the description text.
- Number – the identifier used by the UI
Now let’s look at some basic queries using the Data API. The most basic query will return all assets for the selected type. This query is in the format
http://{server}/{instance name}/rest-1.v1/Data/{asset type}
As an example, http://localhost/VersionOne/rest-1.v1/Data/Scope returns all project data from the VersionOne application running on my local machine. If you receive an error verify the URL by removing ‘‘/rest-1.v1/Data/Scope’’, and also check for spelling and case on the asset type (they are case sensitive). Also note that when using the Data API the browser will prompt you for credentials unless you are using integrated security or the browser has cached your credentials.
Next let’s see how to filter query results. Consider a case where we want to retrieve the Story we see in our backlog with the ID ‘S-01001’. Remember, ‘ID’ in the UI is ‘Number’ to the API, so we need to query Story assets with a where clause that only returns’S-01001’. This query looks like this:
http://localhost/VersionOne/rest-1.v1/data/Story?where=Number='S-01001'
The important things to note here are the question mark between the asset type and the parameter ‘where’ and the tick marks around the value. To reduce the amount of information being returned we can use the ‘sel’ parameter to select specific attributes. Try the following example
http://localhost/VersionOne/rest-1.v1/Data/Story?where=Number='B-01001'&sel=Name,Description,Number
Note the ampersand sign before the ‘sel’ parameter.
I hope this basic information about our API has been informative. In the next issue I’ll cover some more advanced queries and show how to improve the appearance of the API results. In the meantime you can use the links below to find out more information about the API and REST, or consider attending one of our API training classes.
More information on the VersionOne Core API (Data, Meta, and Localization) can be found at
http://community.versionone.com/sdk/Documentation/CoreAPI.aspx
More information about Representational State Transfer (REST) can be found at
http://en.wikipedia.org/wiki/Representational_State_Transfer
More information about API training classes can be found at
http://community.versionone.com/training
Comments