Keyset pagination on primary key
In order to offer a more efficient paging strategy, we are going to implement keyset based pagination for all API endpoints based on the primary key (
- Keyset pagination by
idis an additional paging strategy for now
- We do not support any custom ordering options, we always sort by
- Documented in https://docs.gitlab.com/ee/api/README.html#pagination
- Optional/stretch: Support sorting by
Switching between pagination strategies
In order to use keyset pagination, a new API parameter
pagination=keyset is introduced. If this is not present in the call, the standard offset based pagination is used.
We introduce a new API parameter
key_offset (name tbd) to indicate the offset for paging. The value is the
id of the last record seen in the previous page. For the current page, this means we're looking at records with
id > $key_offset (when ordering by
In absence of
key_offset, the first page is returned.
The size of one page can be changed with
per_page parameter. This behaves the same as with offset based pagination: Defaults to
20 and a maximum is
If keyset pagination is used in combination with a
sort parameter that is not supported by keyset pagination, we fail the request with an appropriate error message/code.
An example of an unsupported request is:
This is because ordering by
created_at isn't available in keyset pagination for now.
Pagination Headers and Link Header
Currently, we provide a
Link header in the response with links to
prev, next, last pages. For keyset pagination, only the
next page will be available.
Keyset pagination is not going to have the following response headers:
X-Next-Page: 3 X-Page: 2 X-Per-Page: 3 X-Prev-Page: 1 X-Total: 8 X-Total-Pages: 3
- Docs for offset pagination: https://docs.gitlab.com/ee/api/README.html#pagination