Problem With How Pagination

[compumike08]

I looked at the documentation in the README on how the library handles pagination (https://github.com/philschatz/octokat.js#paged-results), and based on that documentation it seems like the only way you can traverse through the paginated results is by calling one of the four methods listed on the response object (i.e. nextPage(), previousPage(), firstPage(), and lastPage()). Is there no way to directly fetch a specific page of results by page number, or to find out how many pages there are total without having to iterate through each page by calling nextPage() repeatedly and counting? Without the ability to quickly get the number of total pages, it is impossible to build a UI that shows the total number of pages available (it can only show if there is a next page or not). Also, the inability to directly fetch a specific page of results by page number makes it virtually impossible to use this library in certain types of workflows and/or with certain JS frameworks. For example, when writing a browser application using React.js and Redux, you won't easily have direct access to the response object itself from the previous call to the API in order to invoke the nextPage() method on it (with the React + Redux workflow, the responses from API calls are supposed to be segregated from the actual interface (the data from the response gets put into the Redux store and it flows to the React UI components from there, but the actual response object never gets persisted; this means you won't have access to the response object from when the first page loaded when you need to invoke the nextPage() method on it to load the next page).

I would strongly suggest you add the ability to fetch a page of data directly by passing in the desired page number, as well as the ability get the total number of pages somehow. I'd also recommend adding support for the GitHub API's per_page option (https://developer.github.com/v3/#pagination) which, when sent as part of the request, overrides the default number of entries returned per page (the default is 100 for most endpoints, and in many cases you would want to have a much smaller number of entries on each page).

@philschatz

[philschatz]

Thanks for submitting the issue!

Getting the total number of results (or pages) is unfortunately not exposed in GitHub's API directly. However, #31 describes a "One Weird Trick™" that might be helpful in obtaining the total number of results.

The ?per_page=3&page=4 is possible in octokat, it just needs to be set as an argument when calling .fetch({per_page: 3}) this example may be useful

Note: The Link Header sub-section of the GitHub API states that constructing the next/previous URLs directly is discouraged.

I hope that helps!

[compumike08]

@philschatz: Thanks for the tip on the trick to getting the total page numbers.

Regarding the Link Header sub-section of the GitHub API that says constructing your own URLs directly is discouraged, I had already read that, but I interpreted that warning differently. I interpreted it to mean that, while manually constructing the entire URL was discouraged, taking the URL from the "link" header response and just swapping out the page number in the page query parameter to fetch a specific page was fine. In GitHub's Traversing with Pagination documentation page, in the Constructing Pagination Links, section, it explains how to fetch a specific page directly using their Octokit.rb library for Ruby. Their Ruby library seems to be able to directly fetch a page number by swapping out the value assigned to the page variable in the query string, so I was hoping that your Octokat.js library could do the same thing. If you're querying an API and the result has, say, 40 pages of data, it's ridiculous to expect users to click a "Next" button 35 times to get to the 35th page.