The documentation is confusing me. The “Limitations” section of the Get Users article states:
This endpoint allows you to retrieve a maximum of 1000 users. If your results exceed this threshold, redefine your search.
The fine print under the per_page input box in the “List or search users” section of the API Explorer says:
The amount of entries per page. Default:
50. Max value:100
Is it 100 or 1000?
Unfortunately, I don’t (yet) have any apps with >100 users that would allow me to test if the actual per_page limit holds.
Why do I care?
I’m implementing client-side sorting functionality that would allow user records to be sorted on multiple fields. For user searches that yield <=100 users, it makes no difference. However, as soon as I have queries that start yielding >100 users, I’m going to start getting inconsistent, and weird/wrong results.
For example, let’s say I want to sort users first by family_name then by given_name. I can call the getUsers endpoint with sort=family_name:1. Once I get a page of results, I can sort the returned page by given_name. However, imagine that I’m calling this query with the per_page=100, and with these criteria, records 97~103 look as follows:
| Record # | family_name |
given_name |
|---|---|---|
| 97 | Johnson | Martha |
| 98 | Johnson | Bill |
| 99 | Johnson | Susan |
| 100 | Johnson | George |
| 101 | Johnson | Alan |
| 102 | Johnson | Oscar |
| 103 | Johnson | Michael |
The first page of results will sort only the given_name of the records <= 100, so it would sort them: Bill, George, Martha, Susan. Then on the next page of results, we’d start with Alan, who probably should have come on the previous page before Bill.
So, if I know that I have to sort >100 records on >1 field, I can pre-fetch all of the pages, and just sort all 1000 by the multiple fields on the client side.
I realize this is kind of an edge case, and I’m not (yet) at the phase of development when this is critical, but the documentation is confusing. Additionally, this would all be moot if it were possible to send multiple sort criteria to the server. Do you think I should put this in as a feature request?