OpenProject Collections API

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 |