Artifact-spec referrers/ API Response

[SteveLasker]

Typical Scenarios

A typical scenario would include a number of reference types. Likely in the 0-12 references per subjectManifest.
Using the Notary v2 use case, and the wabbit-networks --> docker hub --> acme rockets workflow, we could imagine the following graph of objects:

• net-monitor:v1 container image
• sbom
  • sbom signature
• security scan results
  • scan result signature
• wabbit-networks signature
• docker hub signature
• acme-rockets import signature
• acme-rockets production signature

Partial visual of the above:

• In the above example, the referrers/ api would return a max of 6 references. (the sbom and scan result signatures aren't returned as they are references to the sbom and scan result).
• The referrers/ api provides for OPTIONAL registry/server side filtering by artifactType. This would enable a client to filter just the example.v0.sbom, the example.v0.scan-result or the cncf.notary.v2 signatures to be returned.
• If the registry supports artifactType filtering, the referrers/ api would return 4 references. The filtering of the acme-rockets production signature is intended to be implemented with annotations (cncf.notary.v2.subject=acme-rockets-production).

Response Payload Requirements

The response payload has the following requirements to consider:

1. Minimize the API calls for a client to get the data it desires. How many round trips of request/response are required to retrieve the specific reference artifact?
2. Maintain the well factored distribution APIs to differentiate manifests (which defines an artifact) and the blobs (that represents the content of the artifact)
3. Minimize the payload response of each request
4. Minimize the server side/registry processing to index and generate the response payload.
5. Provide server and client side filtering of the payload response. Server side filtering is optionally scoped to an artifactType, but may support annotation filtering in the future.
6. Provide paging for larger results
7. Be agnostic for the type of artifacts that may be reference types. (Signatures, SBoM, Scan Results)

Design Options

There have been a number of design proposals for what the referrers api should return. They've centered on two top level proposals:

1. A list of descriptors
2. A list of manifests

There's another dimension for what role a data element might provide.

Using the typical scenario, how can we balance the requirements for what to return in the referrers/ api?