Dealing with Collections

When a route returns an array, most of time it means that the resource is paginated. You can double check it by verifying Response headers. Pagination headers looks like this:

"x-pagination-limit": "10",
"x-pagination-limit-max": "50",
"x-pagination-offset": "0",
"x-pagination-size": "104",

The first important point about Collections with Tuleap REST API is that x-pagination-size might not represent the amount of data that you will be able to actually fetch.

For most routes, it’s too resource intensive to compute the permissions for each and every element of the collection being returned “just” to be about to count them.

So for most routes, x-pagination-size gives the maximum number of matching elements.

The second important point is that pages (slices) you will be getting might be empty if you don’t have the permission to read the elements.

Let say you have x-pagination-size equals to 200 and x-pagination-limit-max equals to 50. You first loop might be able to return 50 elements (because you can read all of them), the second only 10, the third 0 (empty set), the fourth 50 again. At the end of the loop you have 110 elements retrieved.

To summarize, in order to properly use Collections you must:

• get the page size from x-pagination-limit-max (so if we change it you will benefit of the change automatically)

• you need to iterate from 0 to x-pagination-size whatever happen, do not - stop on empty collections (you will be missing data) - stop when you retrieved x-pagination-size elements (you will have an infinite loop)