XML Response Reference

Responses returned from the API have the content type "text/xml", by default. The syntax of the responses varies depending on the query, update, or operation executed.

Query Responses

Responses for queries vary depending on what information was asked for. First, queries are seperated into historical and non-historical, and then seperated into the type of query. These types include Asset Type, Asset, and finally Attribute queries.

Query Data Responses

Data queries are the result of asking for a URL using the "/Data" portion of the path. These queries are for the current state of assets not the historical states.

Asset Type Query

The Asset Type query is a query to retrieve all assets of a given asset type in a single list. This list can be sorted, filtered, and paged.

The response will begin with an "Asset" node and it will contain attributes named "total", "pageSize", and "pageStart". The "total" attribute correspond to the total number of assets that would appear if the query was not paged. The "pageSize" attribute indicates how many assets were returned in a given page. Finally the "pageStart" attribute indicates where in the un-paged asset list this response begins at.

Inside the "Assets" node are any number of "Asset" nodes which correspond to the individual assets that met the filtered parameter. Each "Asset" node contains an "href" attribute which indicates the URL that the given asset resides at and it also contains an "id" attribute which is the internal ID used by VersionOne to uniquely identify the given asset.

Under each "Asset" node are any number of "Attribute" and "Relation" nodes. These nodes correspond to the attributes that make up the given instance of an asset type. Both nodes will contain a "name" attribute which identifes the name of the attribute the node represents. "Attribute" nodes will contain their value as an inner Text element. "Relation" nodes will contain one or more "Asset" nodes which are references to other assets that this specific asset relates to. Each "Asset" reference node will contain an "href" attribute which points to the instance of the related asset, and an "idref" attribute which identifies the unique VersionOne id of the related asset.

<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>

Asset Query

An asset response is returned when a specific asset is asked for. It corresponds to the "Asset" sub node under the "Assets" root node described in the previous section. And example of an asset query is show below.

<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>

Attribute Query

And attribute response is returned when a specific attribute on a specific asset is asked for. As described in the Asset Type Query section above, the node name may either be "Attribute" or "Relation". These nodes will also contain an "of" attribute which is a URL that points to the asset that this attribute is on.

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

Query Historical Responses

Historical queries are executed in the same fashion as regular queries however their response is formatted differently. This is due to the fact that multiple records or nodes are returned for a particular query. Historical queries use the "/Hist" portion of the URL path.

Asset Type Query

When asking for historical asset types, the root node will be called "History". Under it will be any number of nodes called "Asset" which correspond to individual assets as they existed at points in time. On the "Asset" nodes the "href" and "id" attributes will now contain a moment number that indicates at what moment the asset changed. The sub nodes "Attribute" and "Relation" are displayed in the same manner as described in the Data Asset Type Query above.

<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>

Asset Query

When asking for the history of a particular asset, the results will be essentially the same as the historical asset type query above. The only difference is that the only assets returned are those that have a specific ID. Otherwise the results look identical to those returned above.

<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>

Attribute Query

The history of an attribute will return a root node named "History" with a number of "Attribute" or "Relation" sub-nodes. Each sub-node corresponds to a moment in time when the asset the attribute exists on has changed. The "Attribute" or "Relation" node will have a "name" attribute that identifes the attribute and an "of" attribute which identifies the asset the attribute is on. Note that the "of" attribute will contain a URL with a moment.

<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>

Update Responses

The response of an update is an "Asset" node that contains an "href" attribute and "id" attribute that include the ID and Moment of the saved asset. Under the "Asset" node are sub nodes that correspond to the changed attributes and relations.

<Asset href="/VersionOne/rest-1.v1/Data/Member/20/173" id="Member:20:173">
	<Attribute name="Phone">555-555-1212</Attribute>
</Asset>

New Responses

The response of a new asset query is a payload that can be posted back to the API to be saved.

<Asset href="/VersionOne/rest-1.v1/New/Story">
	<Relation name="Scope" act="set">
		<Asset href="/VersionOne/rest-1.v1/Data/Scope/1000" idref="Scope:1000" />
	</Relation>
</Asset>

<Asset href="/VersionOne/rest-1.v1/New/Story">
	<Relation name="Scope" act="set">
		<Asset href="/VersionOne/rest-1.v1/Data/Scope/1009" idref="Scope:1009" />
	</Relation>
	<Attribute name="Description" act="set"><P>When an item's status is updated, alert the owner of the change in status value.</P></Attribute>
	<Attribute name="RequestedBy" act="set">Joe Customer</Attribute>
	<Attribute name="Name" act="set">Integrate with Palm Handheld</Attribute>
	<Relation name="Requests">
		<Asset href="/VersionOne/rest-1.v1/Data/Request/1684" idref="Request:1684" act="add" />
	</Relation>
</Asset>

The response contains an "Asset" node and multiple "Attribute" or "Relation" sub nodes that identify the values that the new asset will contain. Note that these pending attributes and relations are pre-marked with the "act" attribute which is used to mark the pending changes.

Operation Responses

The response of an operation is generally an "Asset" node with an "href" attribute and "id" attribute containing an ID and Moment.

<Asset href="/VersionOne/rest-1.v1/Data/Story/1021/2365" id="Story:1021:2365" />

<Asset href="/VersionOne/rest-1.v1/Data/Timebox/2011/2254" id="Timebox:2011:2254" />

Query Responses​

Query Data Responses​

Asset Type Query​

Asset Query​

Attribute Query​

Query Historical Responses​

Asset Type Query​

Asset Query​

Attribute Query​

Update Responses​

New Responses​

Operation Responses​

Query Responses

Query Data Responses

Asset Type Query

Asset Query

Attribute Query

Query Historical Responses

Asset Type Query

Asset Query

Attribute Query

Update Responses

New Responses

Operation Responses