Sorting and Filters
REST API supports filtering by fields and nested fields. To set a requested filter use
where=condition query parameter. For example, this request will return all bugs in a "In Progress" state:
/api/v1/Bugs?where=EntityState.Name eq 'In Progress'
You can combine several filtering conditions using operator and:
/api/v1/Bugs?where=(CreateDate gt '2011-01-01')and(EndDate lt '2011-02-01')
- Before Targetprocess 3.13.2 the operator 'and' was case-sensitive, so it had to be in lower case (e.g. 'AND' or 'And' were not working).
- Before Targetprocess 3.13.2 in order to combine several rules you had to use logical grouping with brackets. Now the brackets are optional.
- The operator 'or' is not supported. Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/53623
Escaping of single quote symbol in values can be done using preceding backslash:
/api/v1/Userstories?where=Name contains '\''
|Equality||Name eq 'My Name'|
|Not equality||Name ne 'My Name'|
|Greater than||Id gt 5|
|Greater than or equal||Project.Id gte 5|
|Less than||CreateDate lt '2011-10-01'|
|Less than or equal||TimeSpent lte 5.0|
|In list||Id in (155,156)|
|Not int list||not supported|
|Is true||IsActive eq 'true'|
|Is false||IsActive eq 'false'|
|Contains||Name contains 'rest'|
|Not contains||Tags not contains '*Major*'|
|Is set||Release is null|
|Is not set||Description is not null|
Filtering by Custom Field values
It is possible to filter out entities by their Custom Field values. You must provide field name in your query. Format is the following:
?where=CustomFields.FieldName eq 'Value'. For example:
/api/v1/Bugs?where=(CustomFields.Browser eq 'Firefox')
When field name contains space, additional quotes should be added into query:
/api/v1/UserStories?where=('CustomFields.Release Notes' is not null)
Filtering by values in Calculated Custom Fields is not supported within REST API.
Filtering by Tags
Filtering by Tags is possible. Here is how to filter User Stories with tag
/api/v1/userstories?where=(Tags contains 'abc')
When a tag has two words in between, the value should be placed into additional double quotes. Here is how to filter User Stories with tag
two words assigned:
/api/v1/userstories?where=(Tags contains "'two words'")
Wildcards are supported. Asterisk
* symbol means there are zero or any number or symbols instead of it. Asterisks can be appended to the beginning or the end of search string, but not into the middle part.
For example, tag
abcdef matches wildcard
/api/v1/userstories?where=(Tags contains '*abc*')
Filtering in nested collections
It is not possible to filter out entities by some attributes of their collections in REST APIv1.
Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/146598
Sometimes you can work around this limitation by querying the collections directly, for example:
api/v1/Assignments? where=(GeneralUser.Id eq 1234)and(Assignable.EntityType.Name eq 'UserStory')& include=[Assignable[Id,Name]]
/api/v1/Relations? include=[Master[EntityType[Name]],Slave[EntityType[Name]]]& where=(Master.EntityType.Name eq 'Request')and(Slave.EntityType.Name eq 'Bug')
With Multiple Teams feature the "Team" field of Assignable API resource became deprecated, so now working with Teams means working with "TeamAssignment" collection.
/api/v1/TeamAssignments? where=(Team.ID eq 1234)and(Assignable.EntityType.Name eq 'UserStory')& include=[Assignable[ID,Name,AssignedTeams[Team,StartDate,EndDate]]]
/api/v1/TeamAssignments? where=(Team.Name eq 'Alpha')and(Assignable.EntityType.Name eq 'Feature')& include=[Assignable[ID,Name,AssignedTeams[Team,StartDate,EndDate]]]
You can order the REST API results using any field (simple or nested). Use
orderbydesc=field to sort data ascending or descending. For example, this request will return all bugs ordered by creation date (recent bugs on top):
It is not possible to sort by more than one criteria.
Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/145911
Updated about 4 years ago