I wish they would have elaborated on to why not to return the total counts. Does anyone have any ideas why this is a bad idea? I thought it would be useful for the consumer so that they can account for pagination?
Founder here. Returning total count is a very expensive action and most users don't use the result. Therefore, by returning paginated results you can allow the users that need that data, to loop through all the paginated pages and get the total count. It may add an extra step but for 98% of users the API will run faster.
It may make sense to expose a separate entry to retrieve the count. That way the 98% of users who don't need it can continue to ignore it, but you won't force the extra overhead of requiring the other 2% to page through all results to get the count.
While count is expensive, it seems it would be less so than full result set retrieval broken up over several requests?
You'll get some additional usage beyond the 2% who need it now (after all, if it's there people will use it while in its absence it would not be considered at all), but on the whole you should be able to find the threshold at which you'd come out ahead by offering it.
Assume that I am building an interface that displays data I have retrieved from your API.
Are you saying that your API would require my interface to mimic your pagination, as opposed to being able to retrieve data in such a way that I could paginate as I saw fit?
you can paginate however you want. The default is the return 10. You can return an amount 1-100 and use the offset parameter to get the next X results.
Maybe I'm missing something, but how can I display pagination of my own choosing if I can't calculate the total number of pages that exist?
More importantly, let's say that I am retrieving the default 10 results per request. Let's say there are 15 results. If I request the second "page", what will the next_url value in the response be?
In other words, how can you provide an accurate next_url in your responses if you're not calculating the total number of results? At some point, aren't you providing a next_url that will return 0 results?
