Paging and RFC5988
imjasonh opened this issue · 4 comments
(Apologies in advance if this has already been discussed and resolved, if there are links to discussions where these have already been hashed out I'm happy to go read those instead)
I've read through the referrers spec proposal (this specific version, for future readers), and have some feedback I thought I'd share, with the goal of clarifying/generalizing the spec, and toward making it easier to propose and accept into distribution-spec when the time comes.
The proposal for pagination is at https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md#paging-results
It specifies consulting the Link rel="next" response header, which should be consider opaque (RFC5988 FTW).
distribution-spec's pagination is described at https://github.com/opencontainers/distribution-spec/blob/main/spec.md#content-discovery
distribution-spec specifies the parameters &n= and &last=<tagname> specifically, and except for specifying that implementations MUST NOT include a Link header when there are no more items, makes no mention of the Link rel="next" header or RFC5988 at all (though some registry implementations might use it; I don't know)
While I agree that leveraging RFC5988 is definitely better, I think consistency with the rest of distribution-spec is paramount. We don't want registry clients or implementations to have to implement two pagination flows, even if the new one is obviously better.
The proposal could instead suggest ("SHOULD") that registries fully leverage RFC5988, for both referrers and traditional tag listing. This SHOULD amendment could be proposed against distribution-spec today, separate from this proposal, probably contingent on a survey of registry implementations in the wild to see how they stack up.
If distribution-spec moves to suggest/SHOULD RFC5988 then perhaps the referrers API could require/MUST it, since it's a new API, but I wouldn't want to leave room for registries to have to support two pagination schemes, or for clients to have to negotiate or navigate them.
Adding a link to #4 for previous discussions
Keeping open to continue the discussion
makes no mention of the Link rel="next" header or RFC5988 at all (though some registry implementations might use it; I don't know)
From the detail.md page, I believe it does call out both the Link header and RFC5988.
We did choose not to specify the exact pagination parameters that a registry must use (many guidelines I've read encourage using opaque tokens instead of numbers or the last object returned), but clients that are following pagination links for the tag API, should be able to do the same for the referrers API. It's also not as clear what the last param should have / would have been for the referrers API -- you could probably make a good argument for the digest, but as the response is actually a list of descriptors, it's less clear.
makes no mention of the Link rel="next" header or RFC5988 at all (though some registry implementations might use it; I don't know)
From the detail.md page, I believe it does call out both the
Linkheader and RFC5988.
Oh thanks for finding that! That's encouraging.
As an aside, I'd probably reword that from "The following headers will be returned with the response:" to "Implementations MUST return the following headers with the response" -- saying something "will" happen isn't really meaningful in the context of a spec where you're trying to tell both sides of a transaction how to ask for data and how to answer. But that's distribution-spec's bug, not yours 🙃
We did choose not to specify the exact pagination parameters that a registry must use (many guidelines I've read encourage using opaque tokens instead of numbers or the
lastobject returned), but clients that are following pagination links for the tag API, should be able to do the same for the referrers API. It's also not as clear what thelastparam should have / would have been for the referrers API -- you could probably make a good argument for thedigest, but as the response is actually a list of descriptors, it's less clear.
Since distribution-spec does reference RFC5988, perhaps it could tighten the language that clients MUST use the Link response header to find the next page, and SHOULD NOT expect specific parameter names. This would give registries more flexibility to change how they express pagination today, and would align better with this proposal's requirements. Perhaps that's worth pushing forward in distribution-spec? It might need a v1.1 since clients had been told to expect ?n= and &latest=.
Closing as updates to the referres api have been merged.