Skip to main content

Query Examples

This section is a series of examples, starting with simpler queries and moving to more advanced queries. Any of these examples are viewable directly in a web browser capable of displaying XML data.

How to Query a Single Asset​

This URL will retrieve the Member with ID 20, with a set of common attributes:

~/rest-1.v1/Data/Member/20

<Asset href="/VersionOne/rest-1.v1/Data/Member/20" id="Member:20">
	<Attribute name="AssetState">64</Attribute>
	<Attribute name="DefaultRole.Name">System Admin</Attribute>
	<Attribute name="Username">admin</Attribute>
	<Attribute name="IsLoginDisabled">false</Attribute>
	<Relation name="DefaultRole">
		<Asset href="/v1.six/rest-1.v1/Data/Role/1" idref="Role:1" />
	</Relation>
	<Attribute name="Name">Administrator</Attribute>
	<Attribute name="Phone" />
	<Attribute name="AssetType">Member</Attribute>
	<Attribute name="Description" />
	<Attribute name="Nickname">Admin</Attribute>
	<Attribute name="Email">admin@demo.com</Attribute>
</Asset>
Remarks

The XML returned will start with a root node called "Asset" which indicates the results are for a single asset not a list of assets. The "Asset" node also contains an "href" attribute, which corresponds to the full URL used to retrieve this asset, as well as an "id" attribute which contains the internal VersionOne ID of the specific asset.

The child nodes of an "Asset" node are a mixture of "Attribute" and "Relation" nodes. Both types of nodes contain a "name" attribute which tells you what Attribute the value corresponds to. While "Attribute" nodes contain their value, a "Relation" node contains an "Asset" sub node that describes the related asset. Note how the "Asset" sub node contains an "href" attribute like the root "Asset" node but contains an "idref" attribute instead of an "id" attribute.

All assets reside at URLs of the same format; "Member" and "20" can be replaced with any asset's type and ID. If no such asset exists, or if you do not have sufficient rights to view it, then the response will be 404 Not Found.

How to Query for Different Attributes​

Retrieve attributes other than the default set by using the sel query parameter.

~/rest-1.v1/Data/Member/20?sel=Name,Email

<Asset href="/VersionOne/rest-1.v1/Data/Member/20" id="Member:20">
	<Attribute name="Email">admin@demo.com</Attribute>
	<Attribute name="Name">Administrator</Attribute>
</Asset>
Remarks

The response contains only those attributes specified.

Best Practice

Whenever possible, use the sel query parameter to choose specific attributes, thereby reducing the load put on the API.

How to Query the Value of a Single Attribute​

Just as each asset resides at its own URL, so does each attribute. This URL retrieves the Name attribute on Member 20:

~/rest-1.v1/Data/Member/20/Name

<Attribute name="Name" href="/VersionOne/rest-1.v1/Data/Member/20/Name" of="/VersionOne/rest-1.v1/Data/Member/20">Administrator</Attribute>
Remarks

The XML returned will start with a root node called "Attribute" or "Relation" which indicates the results are for a single attribute on a single asset. The root node also contains a "name" attribute, which identifies the attribute the value corresponds to, an "href" attribute, which corresponds to the full URL used to retrieve this attribute, as well as an "of" attribute which corresponds to the full URL used to retrieve the asset this attribute belongs to.

If the root node is "Attribute" the scalar value will be in a Text node inside the root node. If the root node is "Relation" there may be one or more "Asset" nodes which are references to the assets the asset relates to.

How to Get a List of All Story Assets​

This URL will retrieve all Story assets (that you have rights to see):

~/rest-1.v1/Data/Story?page=100,0

<Assets total="10" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1021" id="Story:1021">
		<Attribute name="Name">Logon</Attribute>
		<Relation name="Status">
			<Asset href="/VersionOne/rest-1.v1/Data/StoryStatus/137" idref="StoryStatus:137" />
		</Relation>
		<Relation name="Timebox">
			<Asset href="/VersionOne/rest-1.v1/Data/Timebox/1022" idref="Timebox:1022" />
		</Relation>
		<Attribute name="DetailEstimate" />
		<Attribute name="AssetType">Story</Attribute>
		<Attribute name="AssetState">128</Attribute>
		<Attribute name="Number">S-01001</Attribute>
		<Attribute name="ToDo" />
		<Attribute name="Order">32</Attribute>
		<Relation name="Parent">
			<Asset href="/VersionOne/rest-1.v1/Data/Theme/1015" idref="Theme:1015" />
		</Relation>
		<Attribute name="Description" />
		<Attribute name="Estimate">2</Attribute>
		<Relation name="Priority">
			<Asset href="/VersionOne/rest-1.v1/Data/WorkitemPriority/140" idref="WorkitemPriority:140" />
		</Relation>
		<Relation name="Scope">
			<Asset href="/VersionOne/rest-1.v1/Data/Scope/1010" idref="Scope:1010" />
		</Relation>
		<Relation name="Owners">
			<Asset href="/VersionOne/rest-1.v1/Data/Member/1000" idref="Member:1000" />
		</Relation>
	</Asset>
	<!-- Additional Asset Nodes -->
</Assets>
Remarks

Depending on your security role, you may not be able to see all the Story assets in the entire system.

The XML returned will start with a root node called "Assets" which indicates the results are list of assets. The "Assets" node also contains a "total" attribute, which tells you how many total items are available if paging is not used, as well as "pageStart" and "pageSize" attributes which indicate where in the given query the items belong. See the Paging Syntax for more information on paging queries.

There is no default page size. A query without a page query parameter returns every asset that matched, however many that is. Every example in this section therefore includes page, and so should every query an integration issues. Note that the total attribute still reports how many assets matched in total, which is how you know whether more pages remain.

How to Query Specific Attributes for a List of Story Assets​

Use the sel query parameter to retrieve attributes other than the default set.

~/rest-1.v1/Data/Story?sel=Name,DetailEstimate&page=100,0

<Assets total="10" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1364" id="Story:1364">
		<Attribute name="Name">Company History</Attribute>
		<Attribute name="DetailEstimate">0</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1616" id="Story:1616">
		<Attribute name="Name">Credit Check 1</Attribute>
		<Attribute name="DetailEstimate" />
	</Asset>
	<!-- Additional Asset Nodes -->
</Assets>

How to Filter a Query​

Filter a query by using the where query parameter. This URL will retrieve only Story assets with a To Do of zero:

~/rest-1.v1/Data/Story?sel=Name,ToDo&where=ToDo='0'&page=100,0

<Assets total="2" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1303" id="Story:1303">
		<Attribute name="Name">Home Page</Attribute>
		<Attribute name="ToDo">0</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1339" id="Story:1339">
		<Attribute name="Name">Contact Us</Attribute>
		<Attribute name="ToDo">0</Attribute>
	</Asset>
</Assets>
Remarks

The number 0 in the where query parameter is surrounded by single-quote marks.

How to Sort a Query​

Sort a query by using the sort query parameter. This URL will retrieve Story assets sorted by increasing Estimate:

~/rest-1.v1/Data/Story?sel=Name,Estimate&sort=Estimate&page=100,0

<Assets total="10" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1068" id="Story:1068">
		<Attribute name="Name">Ticket 3432</Attribute>
		<Attribute name="Estimate">1</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1067" id="Story:1067">
		<Attribute name="Name">Ticket 3431</Attribute>
		<Attribute name="Estimate">2</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1845" id="Story:1845">
		<Attribute name="Name">Shipping Lanes - Freight</Attribute>
		<Attribute name="Estimate">3</Attribute>
	</Asset>
	<!-- Additional Asset Nodes -->
</Assets>
Remarks

To sort in descending order prepend the attribute name with a minus sign: sort=-Estimate.

How to Select a Portion of Query Results​

Retrieve a "page" of query results by using the page query parameter. This URL will retrieve the first 5 Story assets:

~/rest-1.v1/Data/Story?sel=Name&page=5,0

<Assets total="10" pageSize="5" pageStart="0">
	<Asset href="/v1.six/rest-1.v1/Data/Story/1021" id="Story:1021">
		<Attribute name="Name">Logon</Attribute>
	</Asset>
	<Asset href="/v1.six/rest-1.v1/Data/Story/1064" id="Story:1064">
		<Attribute name="Name">Ticket 3428</Attribute>
	</Asset>
	<Asset href="/v1.six/rest-1.v1/Data/Story/1065" id="Story:1065">
		<Attribute name="Name">Ticket 3429</Attribute>
	</Asset>
	<Asset href="/v1.six/rest-1.v1/Data/Story/1066" id="Story:1066">
		<Attribute name="Name">Ticket 3430</Attribute>
	</Asset>
	<Asset href="/v1.six/rest-1.v1/Data/Story/1067" id="Story:1067">
		<Attribute name="Name">Ticket 3431</Attribute>
	</Asset>
</Assets>
Remarks

The page query parameter shown asks for 5 items, starting at position 0. The next 5 items can be retrieve with page=5,5.

The pageSize and pageStart attributes reflect the requested page, and the total attribute indicates how many assets satisfied the query in total.

Note that the page size comes first and the starting position second. Reversing them is silent: page=0,50 asks for a page of zero items rather than the first fifty.

Paging is not optional in practice. Because there is no default page size, an unpaged query against a mature instance can attempt to return tens of thousands of assets in a single response. Combined with the default attribute set returned when sel is omitted, this is the most common cause of avoidable load on an Agility instance. Send both page and sel on every query an integration issues, and a sort as well, so that paging is stable between requests.

How to Search Text Attributes​

Search for a string in text attributes by using the find and findin query parameters. This URL will retrieve all Story assets whose Name attribute contains the word Ticket.

~/rest-1.v1/Data/Story?sel=Name&find=Ticket&findin=Name&page=100,0

<Assets total="3" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1065" id="Story:1065">
		<Attribute name="Name">Ticket 3429</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1530" id="Story:1530">
		<Attribute name="Name">Ticket 3449</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1518" id="Story:1518">
		<Attribute name="Name">Ticket 3439</Attribute>
	</Asset>
</Assets>
Remarks

The findin query parameter is optional; if omitted, a base set of attributes will be searched. On the other hand, the findin query parameter may contain multiple text attributes as a comma-delimited list: findin=Name,Description,Reference.

How to Query the History of a Single Asset​

This URL will retrieve the history of the Member asset with ID 20.

~/rest-1.v1/Hist/Member/20

<History total="2" pageSize="2147483647" pageStart="0">
	<Asset href="VersionOne/rest-1.v1/Data/Member/20/0" id="Member:20:0">
		<Attribute name="Description" />
		<Attribute name="Nickname">Admin</Attribute>
		<Attribute name="Email" />
		<Attribute name="AssetState">64</Attribute>
		<Attribute name="DefaultRole.Name">System Admin</Attribute>
		<Attribute name="Username">admin</Attribute>
		<Attribute name="IsLoginDisabled">false</Attribute>
		<Relation name="DefaultRole">
			<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
		</Relation>
		<Attribute name="Name">Administrator</Attribute>
		<Attribute name="Phone" />
		<Attribute name="AssetType">Member</Attribute>
	</Asset>
	<Asset href="VersionOne/rest-1.v1/Data/Member/20/113" id="Member:20:113">
		<Attribute name="Description" />
		<Attribute name="Nickname">Admin</Attribute>
		<Attribute name="Email">admin@demo.com</Attribute>
		<Attribute name="AssetState">64</Attribute>
		<Attribute name="DefaultRole.Name">System Admin</Attribute>
		<Attribute name="Username">admin</Attribute>
		<Attribute name="IsLoginDisabled">false</Attribute>
		<Relation name="DefaultRole">
			<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
		</Relation>
		<Attribute name="Name">Administrator</Attribute>
		<Attribute name="Phone">555-555-1212</Attribute>
		<Attribute name="AssetType">Member</Attribute>
	</Asset>
</History>
Remarks

This example queries from the Hist namespace, instead of the Data namespace. It responds with 2 historical versions of the same asset. The differences between the two historical assets may be difficult to spot—both the Email attribute and the Phone attribute changed.

The root node is named "History" to indicate you are viewing a historical result. The "href" attribute on each "Asset" node contains a moment after the asset type and ID portions of the path. That URL provides the path to the exact version of that specific asset, as it was at that moment.

Note how the first asset can be retrieved using moment number 0, while the second can be retrieved using moment number 113. This indicates that over 100 changes occured to other assets in the system before someone changed this Member asset.

How to Filter a History Query Without an OID​

The Hist namespace is not limited to a single asset addressed by ID. You can query the whole collection and narrow it with where, exactly as in the Data namespace — history is just another queryable projection:

~/rest-1.v1/Hist/Member?where=IsSelf='true'&sel=Name

That returns every historical version of the matching members. Filtering on a business attribute — Hist/Member?where=Email='someone@example.com' — is often more convenient than first resolving the OID and then addressing it by path.

Because a Hist query returns every version of every matching asset, keep it narrow: filter tightly and select only the attributes you need.

How to Query the History of a Single Attribute​

This URL will retrieve the history of changes to the Email attribute of the Member asset with ID 20:

~/rest-1.v1/Hist/Member/20/Email

<History total="2" pageSize="2147483647" pageStart="0">
	<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/0/Email" of="/VersionOne/rest-1.v1/Data/Member/20/0" />
	<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/113/Email" of="/VersionOne/rest-1.v1/Data/Member/20/113">admin@demo.com</Attribute>
</History>
Remarks

The root "History" node contains child nodes named "Attribute", indicating this is a historical query for a single attribute. As with normal attribute queries, the "Attribute" node contains a "name" attribute which identifies the name of the attribute on the asset, an "href" attribute which points to the specific attribute, and finally an "of" attribute which points to the asset the attribute is on. Note how both the "of" and "href" attributes contain a URL with a moment number.

How to Query the History of Many Assets​

This URL will retrieve history for all Story assets you are able to see:

~/rest-1.v1/Hist/Story?sel=Name,ToDo,ChangeDate&page=100,0

<History total="203" pageSize="100" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:818">
		<Attribute name="Name">Company History</Attribute>
		<Attribute name="ToDo">40</Attribute>
		<Attribute name="ChangeDate">2005-08-01T12:28:35.577</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:874">
		<Attribute name="Name">Company History</Attribute>
		<Attribute name="ToDo">20</Attribute>
		<Attribute name="ChangeDate">2005-08-02T11:05:12.123</Attribute>
	</Asset>
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/903" id="Story:1364:903">
		<Attribute name="Name">Company History</Attribute>
		<Attribute name="ToDo">0</Attribute>
		<Attribute name="ChangeDate">2005-08-03T13:09:05.983</Attribute>
	</Asset>
	<!-- Additional Asset Nodes -->
</History>
Remarks

Again, the response is a list of historical assets. Note how each "Asset" has an "href" attribute with a moment number.

Paging matters more here than on a Data query. A history query returns one asset per version rather than one per asset, so an unpaged history query across an entire asset type is typically the largest response the API can produce. See the Paging Syntax.

One of the attributes requested in this example is the ChangeDate attribute. This attribute is maintained by history and it indicates the exact time this change occurred.

All of the previously demonstrated query parameters can be used with historical queries also.

How to Query an Asset "as of" a Specific Time​

Use the asof query parameter to retrieve data as it existed at some point in time. This URL finds the version of a Story asset as it existed at 5:30 PM on August 3rd, 2005:

~/rest-1.v1/Hist/Story/1364?asof=2005-08-03T17:30:00.00&sel=Name,ToDo,ChangeDate

<History total="1" pageSize="2147483647" pageStart="0">
	<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/903" id="Story:1364:903">
		<Attribute name="Name">Company History</Attribute>
		<Attribute name="ChangeDate">2005-08-03T13:09:05.983</Attribute>
		<Attribute name="ToDo">0</Attribute>
	</Asset>
</History>
Remarks

This query returns the last historical record on or before the date specified in the asof query string. Notice how the ChangeDate attribute indicates it was last changed at 1:09 PM on August 3rd, 2005. Between 1:09 PM and 5:30 PM no other changes occurred for this Story asset.

The asof query parameter can also be used on single-attribute and multi-asset historical queries.