Skip to content

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 with WHERE tags.name > '<*last* query param value>'. To fetch the previous page we'll need to do WHERE tags.name < '<*before* query param value>'.

    While it could make more sense to name this parameter first instead of before (to go along with the current last), before is less dubious, and now I think we made a small mistake by carrying over the first name from the Docker V2 spec pagination. So we can go ahead with before for this new parameter and later rename first to after 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 response Link header as per RFC5988.

    For example, for tags a b c d e f, with page size 2, and the current page being c and d, the Link 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 us a and b, while visiting the next rel link will give us e and f.

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.

Edited by João Pereira