From 654a2fd7c210979b6a2cbab99307ea840c949e43 Mon Sep 17 00:00:00 2001 From: Brandon Mitchell <git@bmitch.net> Date: Sat, 30 Mar 2024 11:17:54 -0400 Subject: [PATCH] Converting the recommended limit to an implementers note Signed-off-by: Brandon Mitchell <git@bmitch.net> --- spec.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index eacc730d..b4a32dc4 100644 --- a/spec.md +++ b/spec.md @@ -548,10 +548,13 @@ The tags MUST be in lexical order. When using the `last` query parameter, the `n` parameter is OPTIONAL. -The registry SHOULD support at least `n=1000` tags in a single response. -The client SHOULD avoid requesting more than `n=1000` tags in a single request. If the registry is unable to return all tags requested by the client, the registry MUST return a `413 Content Too Large` with `TAG_LIMIT_EXCEEDED` error <sup>[code-15](#error-codes)</sup> and include the header `OCI-Tag-Limit: <limit>`, where `<limit>` is the maximum tags per request supported by the registry. +*Implementers note:* +Most registries support at least 1000 tags per request, but limits have been seen as low as 50 tags per request. +To maximize the tags per page, a request without setting `n` can be used, which should either return the full list of tags, or an error with the `OCI-Tag-Limit` header indicating the limit. +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.