API: Collections

Whenever a client calls a resource that can return more than one element, it will receive a collection of elements. However as collections can become quite large, the API will not simply return a JSON array, but a special collection object that will contain the actual elements in its embedded property elements.

Collections may be paginated, this means that a single response from the server will not contain all elements of the collection, but only a subset. In this case the client can issue further requests to retrieve the remaining elements. There are two ways to access the result pages of a paginated collection:

  • offset based pagination

  • cursor based pagination

The available ways of pagination depend on the collection queried. Some collections feature no pagination at all, meaning they will always return all elements. Others might only offer one of the two pagination methods or both of them.

A collection also carries meta information like the total count of elements in the collection or - in case of a paginated collection - the amount of elements returned in this response and action links to retrieve the remaining elements.

Local Properties

Property Description Type Availability
total The total amount of elements available in the collection Integer always
pageSize Amount of elements that a response will hold Integer when paginated
count Actual amount of elements in this response Integer always
offset The page number that is requested from paginated collection Integer when offset based available
groups Summarized information about aggregation groups Object when grouping
totalSums Aggregations of supported values for elements of the collection Object when showing sums
Link Description Availability
self Link to the current page in the collection always
changeSize Templated link to change the page size, might change relative position when paginated
jumpTo Templated link to jump to a specified offset when offset based available
nextByOffset Link to retrieve the following page of elements (offset based) when offset based available
previousByOffset Link to retrieve the preceding page of elements (offset based) when offset based available
nextByCursor Link to retrieve the elements following the current page (cursor based) when cursor based available
previousByCursor Link to retrieve the elements preceding the current page (cursor based) when cursor based available

Methods

View aggregated result

groupBy
string

optional query

The column to group by. Note: Aggregation is as of now only supported by the work package collection. You can pass any column name as returned by the queries endpoint.

Example:
status

showSums
boolean

optional query

Default:
false

Example:
true

200

OK