Add ability to perform backward pagination in List Repository Tags API
Context
This is required to support &10208 (closed) and &8507. This is related to the new List Repository Tags API endpoint.
Problem
In order to make this registry endpoint compatible with the GraphQL external pagination (that GitLab Rails will rely on), we need to extend the API with the ability to fetch a previous page.
Right now, we can only move forward. As described in the docs, this is done by accepting a last
query parameter (set to the name of the last tag in the current page) and by filling the Link
response header with a next
link pointing the client to the next page.
Note that we can't simply ask Rails to set last
to the name of the first tag in the Current page - 2
page, because the external pagination mechanism does not keep track of the previous pages contents. So we must provide a Link
header with both next
and previous
links for automated navigation. This is explained in more detail in gitlab#403314 (comment 1382766442).
Required Changes
-
Add support for a
before
query parameter. This can be used by clients to request the previous page.When set to
a
, the registry should perform a query search in the opposite sorting order. As of today, tags are sorted in ascending order (but descending order will be possible after #1000 (closed)), so when looking for the next page we perform a query withWHERE tags.name > '<*last* query param value>'
. To fetch the previous page we'll need to doWHERE tags.name < '<*before* query param value>'
.While it could make more sense to name this parameter
first
instead ofbefore
(to go along with the currentlast
),before
is less dubious, and now I think we made a small mistake by carrying over thefirst
name from the Docker V2 spec pagination. So we can go ahead withbefore
for this new parameter and later renamefirst
toafter
for consistency. -
When handing over a given page to clients, if there is a previous page, we should include a
previous
relative link in the responseLink
header as per RFC5988.For example, for tags
a
b
c
d
e
f
, with page size 2, and the current page beingc
andd
, theLink
header should be set to:Link: <https://registry.gitlab.com/gitlab/v1/repositories/mygroup/myproject/tags/list/?n=2&before=c>; rel="previous", <https://registry.gitlab.com/gitlab/v1/repositories/mygroup/myproject/tags/list/?n=2&last=d>; rel="next"
Visiting the
previous
rel link will give usa
andb
, while visiting thenext
rel link will give use
andf
.
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.