Adding Support for Pagination in .NET SDKs

APIMatic now supports four widely-used pagination strategies in .NET 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 pagination support, .NET 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 .NET SDK provides a consistent interface across all pagination types.

Async

For asynchronous API calls, the endpoint function will return an instance of AsyncPageable.

int? page = 1;
int? size = 25;
try
{
    AsyncPageable<TItem, BasePagedResponse<TItem, TPage>> result = controller.FetchDataAsync(
        page,
        size
    );

    // Iterating over items in all the pages.
    await foreach (var item in result)
    {
        Console.WriteLine(item);
    }

    // Iterating over all the pages.
    await foreach (var pagedResponse in result.GetPagesAsync())
    {
        // Iterating over items in the current page.
        foreach (var item in pagedResponse.Items)
        {
            Console.WriteLine(item);
        }
        // Extracting paged response body.
        Console.WriteLine(pagedResponse.Data);
    }
}
catch (ApiException e)
{
    // Handle exceptions such as API errors or connectivity issues.
    Console.WriteLine(e.Message);
}

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

1. result is IAsyncEnumerable<TItem>. It yields all items from all pages asynchronously.
2. result.GetPagesAsync() is IAsyncEnumerable<BasePagedResponse<TItem, TPage>>. It yields all pages along with their metadata asynchronously.

Sync

For synchronous API calls, the endpoint function will return an instance of Pageable.

int? page = 1;
int? size = 25;
try
{
    Pageable<TItem, BasePagedResponse<TItem, TPage>> result = controller.FetchData(
        page,
        size
    );

    // Iterating over items in all the pages.
    foreach (var item in result)
    {
        Console.WriteLine(item);
    }

    // Iterating over all the pages.
    foreach (var pagedResponse in result.GetPagesAsync())
    {
        // Iterating over items in the current page.
        foreach (var item in pagedResponse.Items)
        {
            Console.WriteLine(item);
        }
        // Extracting paged response body.
        Console.WriteLine(pagedResponse.Data);
    }
}
catch (ApiException e)
{
    // Handle exceptions such as API errors or connectivity issues.
    Console.WriteLine(e.Message);
}

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

1. result is IEnumerable<TItem>. It yields all items from all pages synchronously.
2. result.GetPages() is IEnumerable<BasePagedResponse<TItem, TPage>>. It yields all pages along with their metadata 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