Adding Support for Pagination in TypeScript SDKs

APIMatic now supports four widely-used pagination strategies in TypeScript 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, TypeScript 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 TypeScript SDK provides a consistent interface across all pagination types. The endpoint function will return an instance of PagedAsyncIterable for asynchronous API calls:

const page = 1;
const size = 25;
const result = controller.fetchData(page, size);

try {
    // Iterating over items in all the pages.
    for await (const item of result) {
        console.log(item);
    }

    // Iterating over all the pages.
    for await (const page of result.pages) {
        // Iterating over items in the current page.
        for (const item of page.items) {
            console.log(item);
        }
        
        // Extracting paged response body.
        console.log(page.body);
    }
} catch (error) {
    console.log(error);
}

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

1. result is async iterable and yields all items from all pages.
2. result.pages returns an async iterable 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