Adding Support for Pagination in Java SDKs

APIMatic now supports four widely-used pagination strategies in Java 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, Java 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

Async

The Java SDK provides a consistent interface across all pagination types. The endpoint function will return an instance of PagedFlux for asynchronous API calls.

Integer page = 1;
Integer size = 25;
PagedFlux<Item, PagedResponse<Item, Page>> result = controller.fetchDataAsync(page, size);

// Iterating over items in all the pages.
result.subscribe(
    item -> System.out.println(item),
    error -> _error.printStackTrace());

// Iterating over all the pages.
result.pages().subscribe(
    pagedResponse -> {
        // Iterating over items in the current page.
        pagedResponse.getItems().forEach(item -> System.out.println(item));

        // Extracting paged response body.
        System.out.println(pagedResponse.getResult());
    },
    error -> _error.printStackTrace());

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

1. result is Flux<I>, where I represents Item. It yeilds all items from all pages asynchronously.
2. result.pages() is Flux<P>, where P represents PagedResponse<Item, Page>. It yeilds all pages along with their meta data asynchronously.

Sync

The Java SDK provides a consistent interface across all pagination types. The endpoint function will return an instance of PagedIterable for synchronous API calls.

Integer page = 1;
Integer size = 25;
PagedIterable<Item, PagedResponse<Item, Page>> result = controller.fetchData(page, size);

try {
    // Iterating over items in all the pages.
    for (PagedSupplier<Item> itemSupplier : result) {
        System.out.println(itemSupplier.get());
    }
} catch (ApiException | IOException e) {
    e.printStackTrace();
}

try {
    // Iterating over all the pages.
    for (PagedSupplier<PagedResponse<Item, Page>> pageSupplier : result.pages()) {
        PagedResponse<Item, Page> pagedResponse = pageSupplier.get();
        // Iterating over items in the current page.
        pagedResponse.getItems().forEach(item -> System.out.println(item));

        // Extracting paged response body.
        System.out.println(pagedResponse.getResult());
    }
} catch (ApiException | IOException e) {
    e.printStackTrace();
}

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

1. result is Iterable<I>, where I represents a PagedSupplier of Item. It yields all items from all pages synchronously.
2. result.pages() is Iterable<P>, where P represents a PagedSupplier of PagedResponse<Item, Page>. It yields all pages along with their meta data synchronously.

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

Learn more about pagination feature