Referrers API for OCI Registries

referrers-api.md

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Referrers API for OCI Registries

Request

/oras/artifacts/v1/<name>/manifests/<digest>/referrers?parameters

Request Parameters

• name string

  The namespace of the repository.

• digest string

  The digest of the manifest.

• artifactType string

  This OPTIONAL query parameter specifies a filter for the type of referrers. Registries MAY honor artifact type to filter the response. Clients MUST verify the artifactType in the referrers.data element of the response.

• n integer

  This OPTIONAL query parameter specifies the number of results to return. It MAY be ignored by registries (for instance, if it's too large or negative). Registries SHOULD provide a default number of results to return.

• nextToken string

  This OPTIONAL query parameter specifies a continuation token which can be used to retrieve additional results from the listing API. This MAY be present in the @nextToken property of a previous response if further results are available on the server.

Response

The response will be a paginated collection of manifest properties along with encoded manifest bytes.

Status Codes

A successful response MUST return an HTTP status 200.

Headers

The response SHOULD include the following headers.

• Content-Length

  The number of bytes in the response body. Registries SHOULD provide a size limit on the response size.

• Content-Type

  The response type. Registries SHOULD set it to application/json.

Body

Success

This paged result MUST return the following elements:

• digest string

  The digest of the subject manifest.

• referrers: array

  An array of objects composed of manifest properties and its targeted content. Some properties are similar to an OCI descriptor.

  • data string

    This OPTIONAL property specifies the encoded bytes of a referrer manifest. The encoding MUST be base 64, as described in RFC4648. The decoded result of this property is the content targeted by the accompanying properties.

  • digest string

    This REQUIRED property is the digest of the targeted content, conforming to the requirements outlined in Digests.

  • size int64

    This REQUIRED property specifies the size, in bytes, of the targeted content. This property exists so that a client will have an expected size for the content before processing. If the length of the targeted content does not match the specified length, the content SHOULD NOT be trusted.

  • mediaType string

    This REQUIRED property contains the media type of the targeted content. Values MUST comply with RFC 6838, including the naming requirements in its section 4.2. The OCI image specification defines several of its own MIME types for resources defined in the specification. Clients MAY use this property to deserialize the targeted content.

The response MAY include the following elements:

• @nextToken string

  This OPTIONAL property specifies an opaque continuation token used for paged results.

Example API Response

200 OK
Content-Type: application/json
Content-Length: 821

{
  "digest": "sha256:139d24c06e66f0f13460b56c0bb883b7cd6784143963342db78a0fb75953b2e7",
  "referrers": [
    {
      "mediaType": "application/vnd.oras.artifact.manifest.v1+json",
      "size": 415,
      "digest": "sha256:217165219e2445fddcb3fbd79221a78f3176e4453b2a56c0a6aa3494b5c936c4",
      "data": "eyJzY2hlbWFWZXJzaW9uIjowLCJtZWRpYVR5cGUiOiJhcHBsaWNhdGlvbi92bmQub3Jhcy5hcnRpZmFjdC5tYW5pZmVzdC52MStqc29uIiwiYXJ0aWZhY3RUeXBlIjoiYXBwbGljYXRpb24vYWNyLmNoZWNraGVhbHRoLmFydGlmYWN0LnRlc3QiLCJibG9icyI6W3siZGlnZXN0Ijoic2hhMjU2OmZkODk5NWZkNzM0NTkzYmNjYWM5NGRiMzk2MzgwYzc4YmViMDU5ODFjODU0OGU5YmFhZjllMTRmNjk4MjU1ZTkiLCJzaXplIjo5NX1dLCJzdWJqZWN0TWFuaWZlc3QiOnsibWVkaWFUeXBlIjoiYXBwbGljYXRpb24vdm5kLm9jaS5pbWFnZS5tYW5pZmVzdC52MStqc29uIiwiZGlnZXN0Ijoic2hhMjU2OjEzOWQyNGMwNmU2NmYwZjEzNDYwYjU2YzBiYjg4M2I3Y2Q2Nzg0MTQzOTYzMzQyZGI3OGEwZmI3NTk1M2IyZTciLCJzaXplIjozMjR9fQ=="
    }
  ]
}

Paging

Registries SHOULD implement paging in their API. Clients MAY request results with a given page size (using the n query parameter) and a nextToken from a previous response. If they do not specify a value for n, a default value SHOULD be applied by the registry.

Why include the entire manifest in the payload?

Pros

• It offers the most flexibility for client-side filteration, including filtering based on annotations.

• Encoded manifests in the response can save one round trip since they are verifiable with the accompanying mediaType, digest and size properties.

  • Manifest owners can choose to leverage the reserved data field within the manifest to reduce the round trips to fetch the referenced blobs.

• The need for expensive server side filtering remains OPTIONAL for registries.

  • As an example, filtering by free form annotations would require registries to parse and process the manifest, leading to increased complexity.

Cons

• Constructing a response consisting of multiple manifests might be an expensive operation for registries with large distributed data stores.