Skip to main content

Pagination

Many APIs return large datasets split across multiple pages. APIMatic supports pagination in generated SDKs through a flexible configuration mechanism in the OpenAPI specification. Developers can use a simple and consistent SDK interface to navigate through paginated results, regardless of the underlying pagination style used by the API.

Pagination Configuration in OpenAPI​

Pagination in APIMatic is configured using the pagination OpenAPI extension. This extension allows specifying how to send pagination inputs in the request and where to extract results or tokens from the response. All pagination configuration fields accept JSON Pointers, enabling fine-grained customization of how request parameters and response structures are interpreted.

Example Usage​

Once the OpenAPI pagination configuration is in place, the generated SDKs provide an easy-to-use interface for consuming paginated responses. The SDKs abstract away the logic of computing page tokens, building follow-up requests, and iterating over datasets.

# Initial request with optional inputs like page number or size.
result = client.orders.list_orders(page=1, size=25)

# Automatically iterate over all items across pages.
try:
    for item in result:
        print(item)
except APIException as e:
    print(f"API error: {e}")

# Or, iterate manually over each page and its 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"API error: {e}")

SDK Interface Details​

result: The paginated response from the endpoint, behaves as an iterator if used in a loop.

result.pages(): An iterator for traversing pages manually.

page.items(): Returns the list of items in the current page.

page.body: The full deserialized response body of the current page.

Error Handling: Wrap pagination logic in try blocks to catch and handle APIException.

Benefits​

  • Uniform SDK Experience: Same interface regardless of pagination strategy.
  • No Extra Logic Needed: No need to parse tokens or handle loop termination manually.
  • OpenAPI-Driven: Automatically applied based on x-pagination configuration.
  • Customizability: Flexible placement of input and output using JSON Pointers.