Pagination

Certain API operations return lists of objects. When the number of objects in the list is large, the API will paginate the results.

The Files.com Ruby SDK provides multiple ways to paginate through lists of objects.

Automatic Pagination

The auto_paging_each method iterates through every object on every page, requesting each page only when iteration reaches it. Without a block it returns a lazy enumerator, so methods such as first(10) request only the pages they need.

Example Request

begin
  files = Files::Folder.list_for(path,
    search: "some-partial-filename"
  )
  files.auto_paging_each do |file|
    # Operate on file
  end
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Manual Pagination

A list operation returns its first page. each, and every other Enumerable method, covers the objects on that page. has_next_page? reports whether another page follows, and next_page requests it. After the last page, next_page returns an empty page without making a request.

All pages of a list share one position for next_page, so calling it again on an earlier page continues after the newest page. auto_paging_each keeps its own position: it starts at the page you call it on and does not move next_page.

Example Request

begin
  page = Files::Folder.list_for(path, per_page: 100)
  loop do
    page.each do |file|
      # Operate on file
    end
    break unless page.has_next_page?
  
    page = page.next_page
  end
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end