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

Links

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