rest-1.v1/Data
Overview
This endpoint provides read, write, and update access to assets. This endpoint queries for simple or complex sets of information, updates information, and executes system-defined operations.
| URL Form |
|
| Authentication | Application |
| HTTP Request Verb | HTTP GET, HTTP POST |
| Response Content Type | text/xml |
For more details on the syntax, see the GitHub project with ANTLR grammars.
Request Parameters
HTTP Verbs
HTTP GET
GET requests are used to query information, and receive an XML response.
HTTP POST
POST requests are used to update information, and include an XML payload to describe the update. POST requests are also used to execute operations, which change data in ways that cannot be accomplished with a simple update (such as re-opening a closed Story).
Salient Features of the XML Response
Assets
When requesting more than a single asset, the assets node helps navigate over the set of assets. The attributes total, pageSize, and pageStart can be used to navigate through a large set.
Asset
The Asset node has an href attribute containing the URL path used to retrieve this asset. The asset node has an id attribute with the OID Token for this asset.
Attribute
Name refers to an Attribute Definition.
Relation
Name refers to an Attribute Definition. Contains another asset node with an idref to the OID Token of the referenced asset.
Examples with OID Token syntax
A Single Asset
The following example returns just one member. Since there is no select parameter, the result includes a default set of attributes.
<Server Base URI>/rest-1.v1/Data/Member/20
A Single Attribute on a Single Asset
The following example returns the same member. Since an attribute is specified as part of the URL path, the result includes only the Name attribute.
<Server Base URI>/rest-1.v1/Data/Member/20/Name
Selecting Multiple Attributes
The following example returns the same member but also uses the select parameter. The result includes only the Name and Email attributes
<Server Base URI>/rest-1.v1/Data/Member/20?sel=Name,Email
Examples with from syntax
Selecting All Assets of a Type
The following example returns all the Story assets in the system available to the authorized member.
<Server Base URI>/rest-1.v1/Data/Story?sel=Name,Number
Paging Results of a Query
The above example can take a long time to return all of the Story assets. The following example uses the page parameter to return the first 5 Stories from the result set.
<Server Base URI>/rest-1.v1/Data/Story?sel=Name,Number&page=5,0
Sorting Results of a Query
The above example with paging is sorted by ID. Use a sort parameter to specify a different sort attribute. The following example uses the sort parameter to return the story with the highest estimate.
<Server Base URI>/rest-1.v1/Data/Story?sel=Name,Number,Estimate&sort=-Estimate&page=1,0
Filtering a Query
The following example uses the where parameter to filter results to only Story assets with a ToDo of zero.
<Server Base URI>/rest-1.v1/Data/Story?sel=Name,Number,Estimate&where=ToDo='0'&page=1,0