Skip to main content

Adding Support for Pagination in Python SDKs

· 2 min read

APIMatic now supports four widely-used pagination strategies in Python 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, Python 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 Python 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
try:
for item in result:
print(item)
except APIException as e:
print(f"Error occurred: {e}")

# Iterating over pages and their items
try:
for page in result.pages():
print("Page body:", page.body)
for item in page.items():
print("Item:", item)
except APIException as e:
print(f"Error occurred: {e}")

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 Pythonic.

Learn more about pagination feature