Class: CoreLibrary::CursorPagination

Inherits:
PaginationStrategy show all
Defined in:
lib/apimatic-core/pagination/strategies/cursor_pagination.rb

Overview

Implements a cursor-based pagination strategy for API responses.

This class manages the extraction and injection of cursor values between API requests and responses, enabling seamless traversal of paginated data.

Instance Attribute Summary

Attributes inherited from PaginationStrategy

#metadata_wrapper

Instance Method Summary collapse

Constructor Details

#initialize(output, input, metadata_wrapper) ⇒ CursorPagination

Initializes a CursorPagination instance with the specified output and input pointers and a metadata wrapper.

Validates that both input and output pointers are provided.

Parameters:

  • output (String) —

    JSON pointer to extract the cursor from the API response.

  • input (String) —

    JSON pointer indicating where to set the cursor in the request.

  • metadata_wrapper (Proc) —

    A callable to wrap paged responses with additional metadata.

Raises:

  • (ArgumentError) —

    If either input or output is nil.



15
16
17
18
19
20
21
22
23
24
 
# File 'lib/apimatic-core/pagination/strategies/cursor_pagination.rb', line 15

def initialize(output, input, metadata_wrapper)
  super metadata_wrapper

  raise ArgumentError, 'Input pointer for cursor based pagination cannot be nil' if input.nil?
  raise ArgumentError, 'Output pointer for cursor based pagination cannot be nil' if output.nil?

  @output = output
  @input = input
  @cursor_value = nil
end

Instance Method Details

#applicable?(response) ⇒ Boolean

Determines whether the cursor pagination strategy is applicable based on the given HTTP response.

Parameters:

  • response (HttpResponse, nil) —

    The response from the previous API call.

Returns:

  • (Boolean) —

    true if this strategy is applicable based on the response; false otherwise.



31
32
33
34
35
36
37
 
# File 'lib/apimatic-core/pagination/strategies/cursor_pagination.rb', line 31

def applicable?(response)
  return true if response.nil?

  @cursor_value = response.get_value_by_json_pointer(@output)

  !@cursor_value.nil?
end

#apply(paginated_data) ⇒ Object?

Advances the pagination by updating the request builder with the next cursor value.

If there is no previous response, initializes the cursor from the request builder. Otherwise, extracts the cursor from the last response using the configured output pointer.

Parameters:

  • paginated_data (Object) —

    An object containing the last response and request builder.

Returns:

  • (Object, nil) —

    A new request builder for the next page, or nil if pagination is complete.



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/apimatic-core/pagination/strategies/cursor_pagination.rb', line 46

def apply(paginated_data)
  last_response = paginated_data.last_response
  request_builder = paginated_data.request_builder

  # If there is no response yet, this is the first page
  if last_response.nil?
    @cursor_value = request_builder.get_parameter_value_by_json_pointer(@input).to_s

    return request_builder
  end

  @cursor_value = last_response.get_value_by_json_pointer(@output)

  return nil if @cursor_value.nil?

  request_builder.get_updated_request_by_json_pointer(@input, @cursor_value)
end

#apply_metadata_wrapper(paged_response) ⇒ Object

Applies the configured metadata wrapper to the paged response, including the current cursor value.

Parameters:

  • paged_response (Object) —

    The response object from the current page.

Returns:

  • (Object) —

    The result of the metadata wrapper applied to the paged response and cursor value.



68
69
70
 
# File 'lib/apimatic-core/pagination/strategies/cursor_pagination.rb', line 68

def apply_metadata_wrapper(paged_response)
  @metadata_wrapper.call(paged_response, @cursor_value)
end