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 (id
column).
- Keyset pagination by
id
is an additional paging strategy for now - We do not support any custom ordering options, we always sort by
id asc
. - Documented in https://docs.gitlab.com/ee/api/README.html#pagination
- Optional/stretch: Support sorting by
id desc
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.
Offset-key parameter
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 id asc
).
In absence of key_offset
, the first page is returned.
per_page
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 100
.
order_by
, sort
params
Unsupported If keyset pagination is used in combination with a order_by
and 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:
GET /projects?order_by=created_at
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
Material/Links
- Docs for offset pagination: https://docs.gitlab.com/ee/api/README.html#pagination
This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.