diff --git a/spec.md b/spec.md index cfb098cb..c9f0d477 100644 --- a/spec.md +++ b/spec.md @@ -529,8 +529,10 @@ In addition to fetching the whole list of tags, a subset of the tags can be fetc In this case, the path will look like the following: `/v2//tags/list?n=` [end-8b](#endpoints) `` is the namespace of the repository, and `` is an integer specifying the number of tags requested. -The response to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository is less than ``. +The response to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository is less than `` or a `Link` header is provided. Otherwise, the response MUST include `` results. +A `Link` header MAY be included in the response when additional tags are available. +If included, the `Link` header MUST be set according to [RFC5988](https://www.rfc-editor.org/rfc/rfc5988.html) with the Relation Type `rel="next"`. When `n` is zero, this endpoint MUST return an empty list, and MUST NOT include a `Link` header. Without the `last` query parameter (described next), the list returned will start at the beginning of the list and include `` results. As above, the tags MUST be in lexical order. @@ -546,6 +548,11 @@ The tags MUST be in lexical order. When using the `last` query parameter, the `n` parameter is OPTIONAL. +*Implementers note:* +Previous versions of this specification did not include the `Link` header. +Clients depending on the number of tags returned matching `n` may prematurely stop pagination on registries using the `Link` header. +When available, clients should prefer the `Link` header over using the `last` parameter for pagination. + ##### Listing Referrers *Note: this feature was added in distibution-spec 1.1.