LinkHeaderPaginationAdapter

Pagination via RFC 5988 Link headers.

1. Overview
2. pagination_parameter_name

Overview

Many REST APIs use the Link header to communicate pagination, following the standard defined in RFC 5988 <https://tools.ietf.org/html/rfc5988>_. The server includes a Link header with rel="next" pointing to the URL for the next page:

Link: <https://api.example.com/users?start=50>; rel="next"

This adapter parses that header and extracts the configured pagination_parameter_name from the next link’s query string to build the pagination data for the next request.

This is the default pagination adapter used by ApiBackend.

Usage

import clearskies

# Explicit usage (this is also the default when no pagination_adapter is provided):
backend = clearskies.backends.ApiBackend(
    base_url="https://api.example.com",
    pagination_adapter=clearskies.backends.adapters.LinkHeaderPaginationAdapter(
        pagination_parameter_name="page",
    ),
)

How it works

Given a response with this header:

Link: <https://api.example.com/users?page=3>; rel="next", <https://api.example.com/users?page=1>; rel="prev"

And pagination_parameter_name="page", this adapter returns {"page": "3"}. That dictionary is then passed back into the next API request as pagination data.

pagination_parameter_name

Optional

The query parameter name to extract from the rel="next" link URL (e.g. "page", "start", "since", "cursor").