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
idis 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.
Unsupported order_by, sort params
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_atThis 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: 3Material/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.