it says here that for the endpoint GET /rest/api/3/users we can send a query parameter called maxResults, with a default value of 50. But what is the maximum value we can give to this parameter? Can I ask for 10,000 users? Or is the default value already the maximum value?
See the “pagination” section of the REST API documentation (link). It explains that:
maxResults is the maximum number of items that a page can return. Each operation can have a different limit for the number of items returned, and these limits may change without notice. To find the maximum number of items that an operation could return, set maxResults to a large number—for example, over 1000—and if the returned value of maxResults is less than the requested value, the returned value is the maximum.
Thank you for the prompt response. But for testing counting the returned values, for example 2000 users, that means I would need to have more than 2000 users in my project to begin with, right? Which seems a bit complicated for some endpoints (like for example, creating hundreds of groups just for testing).
If there is no other way, I guess I will have to take the default value as a sort of ‘fail-safe’ maximum.
For a bit of “history”, these API parameters are application properties that Server/DC administrators can override for better API performance (or worse if they do it badly). For Cloud, the values are controlled by Atlassian. As @kkercz’s reference indicates, we reserve the right to change the value as performance dictates; hence, the need to respect the pagination scheme.
That said, I remember doing some experiments once and finding the maxResults was always the same as the default (again, with the caveat that this may change). You may want to do your own experiments, especially if you are interested in a specific endpoint like users. However, I think the practical advice is that Atlassian has already set the default to the maximum, so don’t worry about that parameter. Let me know if you find otherwise.
Several comments about the problems with undocumented pagination limits.
In the case of /rest/api/3/users the default maxUsers is 50 but as I checked we can set it larger, at least 100. But I have not checked what is the actual maximum, don’t have a large Cloud site where to test it.
If developers would rely on the default and if we request /rest/api/3/users and get 100 results then we do not know if these are all 100 users or maxUsers are limited at 100. Therefore we would always need to request /rest/api/3/users?startAt=100 to validate it.
If we would use /rest/api/3/users?maxUsers=1000 and get only 100 results then we also don’t know if these are all results as probably maxUsers is limited just to 100 results. And we would need to make another request /rest/api/3/users?maxUsers=1000&startAt=1000 to validate it.
One more problem with /rest/api/3/users is that it cannot be used from Connect apps. For the additional confusion there is /rest/api/3/users/search which also cannot be used from Connect apps. But there is very similarly looking /rest/api/3/user/search which can be used from Connect apps. All these are returning just arrays of user objects without the possibility to see enforced maxResults.
I would like to know, where server or dc admins can set those parameters and how?
We ran in the issue that GET /rest/user/search is limited to a maxResults of 99 ( after update 8.14 to 8.20 )
In other words, you cannot set the API maxResults directly, but you can influence them with this search behavior. I don’t know if it applies to user search.