Partial response (includes and excludes)

By default, server returns an entity with its default set of fields. However, you can request an entity with some selected data only. Thus you can include additional fields or resources or reduce traffic, memory and CPU usage.

Includes

You can explicitly specify attributes that you want to have in the response. It is possible to include Fields, Custom Fields, Collections and Nested Entities (with inner Fields). The general format is:

GET /api/v1/{Entities}/?include=[Field1,Field2,CustomFields,Collection1,NestedEntity[Field3]]

For example, let's request Bugs with Names, Description, Attachments and Iteration Name

GET /api/v1/Bugs/?include=[Name, Description, Attachments, Iteration[Name]]

<Bugs>
 <Bug Id="214" Name="Javascript error (null reference) on form validation">
 <Description>Some steps</Description>
 <Iteration Id="44" Name="Sprint #2.2"/>
 <Attachments/>
 </Bug>
 <Bug Id="213" Name="Typos on Contacts page">
 <Description nil="true"/>
 <Iteration Id="44" Name="Sprint #2.2"/>
 <Attachments/>
 </Bug>
</Bugs>

Custom Fields

GET /api/v1/UserStories/?include=[CustomFields]

All fields are always retrieved when you include CustomFields list to your query. It is not possible to include some selected custom fields only in API v1.

It is not possible to include Custom Fields of neither parent nor nested entities. Query Custom Fields of parent and child entities within two separate requests and then parse and merge results on the client side.

Nested Entities

Entity Id and Nested Entity Id are always included into response. Also if you request Nested Entity without parameters, it will contain Id and Name.

GET /api/v1/Bugs/?include=[Iteration]

<Bugs>
 <Bug Id="214">
 <Iteration Id="44" Name="Sprint #2.2"/>
 </Bug>
 <Bug Id="213">
 <Iteration Id="44" Name="Sprint #2.2"/>
 </Bug>
</Bugs>

You can use the same rule for Nested Collections.

GET /api/v1/UserStories/?include=[Tasks[Name,Description,Effort]]

🚧

Depth of hierarchical nesting is limited

It is not possible to retrieve all nested entities from other list of nested entities within single API call using top-to-bottom approach. For example, it is not possible to retrieve Epics with all inner Features and all inner User Stories. Try to use bottom-to-top method when possible and compose data from multiple API calls on your side further.

Excludes

If you want to exclude some attributes from Entity response, you can use exclude parameter. For example, you don't want to have the Description field in the response.

GET /api/v1/UserStories/?exclude=[Description]

🚧

It is not possible to use includes and excludes simultaneously in a single request. For example, this request exclude=[Name]&include=[Description] returns 400 error.

Examples

How to receive all users assigned to the user story?

GET /api/v1/UserStories/35429/Assignments?include=[Role[Name],GeneralUser[FirstName,LastName]]

How to extract all closed user stories last year?

GET /api/v1/UserStories?take=1000&where=(EntityState.Name eq 'Done') and (EndDate gt '2011-01-01')