opencontainers / opencontainers/distribution-spec

Proposal: Change the requirements on tags list and catalog pagination

Open
#116 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
1.1k
Forks
260
Avg merge
3d 23h
Merged PRs (30d)
1

Description

Currently, the tags list API and catalog both specify pagination is to occur via the n and last parameters (see: https://github.com/opencontainers/distribution-spec/blob/master/spec.md#tags)

However, the spec also states:

Compliant client implementations SHOULD always use the Link header value when proceeding through results linearly. The client MAY construct URLs to skip forward in the list of tags.

Since implementations are returning the Link header and clients are (AFIAK) nearly always using the Link header to continue the pagination, I'd like to propose that we reduce the requirements, to allow implementations to only support linear iteration via the Link header if they so choose.

For example, Quay currently (in violation of the spec) returns an encoded next_page token rather than last, as it is a much more efficient means of looking up the continuation point for pagination. As this appears to work with all clients today, despite violating the current specification, we'd prefer to not add support for the unoptimized scenario unless absolutely necessary.

I recognize this is a breaking change and, as such, may not be doable, but I thought I'd put it out there anyway :)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the tags pagination section in spec.md#tags and review the current requirements for n, last, and the Link header. Compare the stated behavior with the Quay example in the issue; done means the proposal has a decided, internally consistent specification change and any compatibility implications are addressed.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.