ParameterPaginationAdapter

Pagination by incrementing a query parameter (page number or offset).

1. Overview
2. pagination_parameter_name
3. start_value
4. step
5. use_limit_as_step

Overview

Some REST APIs paginate by accepting a query parameter like ?page=2 or ?offset=50, and the client is responsible for incrementing the value to fetch the next page. This adapter handles that pattern by reading the current pagination value from the query and incrementing it based on the configured step.

The adapter determines whether there are more pages by comparing the number of records returned against the query’s limit. If the response contains fewer records than the limit, there are no more pages.

Page-based pagination

For APIs that use ?page=1, ?page=2, etc:

import clearskies

backend = clearskies.backends.ApiBackend(
    base_url="https://api.example.com",
    pagination_parameter_name="page",
    pagination_adapter=clearskies.backends.adapters.ParameterPaginationAdapter(
        pagination_parameter_name="page",
        start_value=1,
        step=1,
    ),
)

Offset-based pagination

For APIs that use ?offset=0, ?offset=50, ?offset=100, etc:

import clearskies

backend = clearskies.backends.ApiBackend(
    base_url="https://api.example.com",
    pagination_parameter_name="offset",
    pagination_adapter=clearskies.backends.adapters.ParameterPaginationAdapter(
        pagination_parameter_name="offset",
        start_value=0,
        use_limit_as_step=True,
    ),
)

With use_limit_as_step=True, the step size automatically matches the query’s limit (e.g. if limit is 50, the offset increments by 50 each page).

pagination_parameter_name

Optional

The query parameter name the API expects for pagination (e.g. "page", "offset", "start").

start_value

Optional

The initial value for the first page (e.g. 1 for page-based, 0 for offset-based).

step

Optional

The increment for each subsequent page (e.g. 1 for page-based). Ignored when use_limit_as_step is True.

use_limit_as_step

Optional

When True, uses the query’s limit as the step size instead of step. Typical for offset-based pagination (e.g. offset increments by 50 when limit is 50).