Was this article helpful?

rest-1.v1/Data

Last modified 14:11, 15 Mar 2014

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.

 

API
URL Form

<Server Base URI>/rest-1.v1/Data/<OID Token>[/<Attribute Definition>]

<Server Base URI>/rest-1.v1/Data/<from>

Authentication OAuth 2.0 or 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.

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

Tags

Comments

You must to post a comment.

Attachments

 
Agile Made Easier