Class: ApiAdaptor::ListResponse

Inherits:
Response
  • Object
show all
Defined in:
lib/api_adaptor/list_response.rb

Overview

Response wrapper for paginated API results.

ListResponse handles paginated responses using Link headers (RFC 5988) for navigation. It expects responses to have a "results" array and provides methods to navigate through pages.

Examples:

Basic usage

response = client.get_list("/posts?page=1")
response.results       # => Array of items on current page
response.next_page?    # => true
response.next_page     # => ListResponse for page 2

Iterating over current page

response.each do |item|
  puts item["title"]
end

Fetching all pages

response.with_subsequent_pages.each do |item|
  puts item["title"]  # Automatically fetches additional pages
end

Instance Method Summary collapse

Methods inherited from Response

#<=>, #[], #blank?, #cache_control, #code, #dig, #expires_at, #expires_in, #headers, #parsed_content, #present?, #raw_response_body, #to_hash

Constructor Details

#initialize(response, api_client, options = {}) ⇒ ListResponse

Initializes a new ListResponse with API client reference for pagination

Parameters:

  • response (RestClient::Response) —

    The raw HTTP response

  • api_client (Base) —

    API client instance for fetching additional pages

  • options (Hash) (defaults to: {}) —

    Configuration options (see Response#initialize)



34
35
36
37
 
# File 'lib/api_adaptor/list_response.rb', line 34

def initialize(response, api_client, options = {})
  super(response, options)
  @api_client = api_client
end

Instance Method Details

#each {|Hash| ... } ⇒ Object

Iterate over results on the current page only

Yields:

  • (Hash) —

    Each result item

See Also:



47
 
# File 'lib/api_adaptor/list_response.rb', line 47

def_delegators :results, :each, :to_ary

#next_page ⇒ ListResponse?

Fetches the next page of results

Results are memoized to avoid refetching the same page multiple times.

Returns:

  • (ListResponse, nil) —

    Next page response or nil if no next page



68
69
70
71
72
73
74
 
# File 'lib/api_adaptor/list_response.rb', line 68

def next_page
  # This shouldn't be a performance problem, since the cache will generally
  # avoid us making multiple requests for the same page, but we shouldn't
  # allow the data to change once it's already been loaded, so long as we
  # retain a reference to any one page in the sequence
  @next_page ||= (@api_client.get_list page_link("next").href if next_page?)
end

#next_page? ⇒ Boolean

Checks if there is a next page available

Returns:

  • (Boolean) —

    true if next page exists



59
60
61
 
# File 'lib/api_adaptor/list_response.rb', line 59

def next_page?
  !page_link("next").nil?
end

#previous_page ⇒ ListResponse?

Fetches the previous page of results

Results are memoized to avoid refetching the same page multiple times.

Returns:

  • (ListResponse, nil) —

    Previous page response or nil if no previous page



88
89
90
91
 
# File 'lib/api_adaptor/list_response.rb', line 88

def previous_page
  # See the note in `next_page` for why this is memoised
  @previous_page ||= (@api_client.get_list(page_link("previous").href) if previous_page?)
end

#previous_page? ⇒ Boolean

Checks if there is a previous page available

Returns:

  • (Boolean) —

    true if previous page exists



79
80
81
 
# File 'lib/api_adaptor/list_response.rb', line 79

def previous_page?
  !page_link("previous").nil?
end

#results ⇒ Array<Hash>

Returns the array of results from the current page

Returns:

  • (Array<Hash>) —

    Array of result items



52
53
54
 
# File 'lib/api_adaptor/list_response.rb', line 52

def results
  to_hash["results"]
end

#to_ary ⇒ Array

Convert results to array

Returns:

  • (Array) —

    Array of result items on current page



47
 
# File 'lib/api_adaptor/list_response.rb', line 47

def_delegators :results, :each, :to_ary

#with_subsequent_pages ⇒ Enumerator

Returns an enumerator that transparently fetches and iterates over all pages

Pages are fetched on demand as you iterate. If you call a method like #count, all pages will be fetched immediately. Results are memoized to avoid duplicate requests.

Examples:

Iterate over all pages

response.with_subsequent_pages.each do |item|
  puts item["title"]
end

Count all items across all pages

total_count = response.with_subsequent_pages.count

Convert all pages to array

all_items = response.with_subsequent_pages.to_a

Returns:

  • (Enumerator) —

    Enumerator for all results across all pages



110
111
112
113
114
115
 
# File 'lib/api_adaptor/list_response.rb', line 110

def with_subsequent_pages
  Enumerator.new do |yielder|
    each { |i| yielder << i }
    next_page.with_subsequent_pages.each { |i| yielder << i } if next_page?
  end
end