Adding Support for Pagination in Ruby SDKs

APIMatic now supports four widely-used pagination strategies in Ruby SDKs: Offset, Page, Cursor, and Link based pagination. This enhancement provides a seamless and unified way to consume paginated API responses, regardless of the underlying mechanism.

Details

Paginated responses are common in REST APIs to improve performance and manage large datasets. With the pagination support, Ruby SDKs automatically detect and handle paginated data based on the OpenAPI specification. This removes the need for manual pagination logic and gives developers a consistent interface to work with.

Each pagination type can be enabled independently using the pagination OpenAPI extension in the OpenAPI specification. Each pagination configuration allows customization of request and response fields using JSON Pointers, giving you full control over how pagination is applied for your specific API format.

Usage Example

The Ruby SDK provides a consistent interface across all pagination types:

# Fetching paginated data (parameters may vary depending on pagination type)
result = client.controller.fetch_data(page: 1, size: 25)

# Iterating over all items across pages
begin
  result.each do |item|
    puts item
  end
rescue APIException => e
  puts "Error occurred: #{e}"
end

# Iterating over pages and their items
begin
  result.pages.each do |page|
    puts "Page body: #{page.data}"  # 'data' is used as the deserialized page body
    page.items.each do |item|
      puts item
    end
  end
rescue APIException => e
  puts "Error occurred: #{e}"
end

Regardless of the pagination type used in the API, the SDK standardizes the developer experience:

1. result is iterable and yields all items from all pages.
2. result.pages returns an iterator for each page object.
3. page.items provides access to items within a specific page.

Pagination tokens, page numbers, offsets, or links are automatically managed by the SDK. This makes integration with paginated APIs straightforward, clean, and idiomatic.

Learn more about pagination feature