Skip to content
This repository has been archived by the owner on May 15, 2024. It is now read-only.

Commit

Permalink
Update referrers to _oras/artifacts/referrers (#83)
Browse files Browse the repository at this point in the history 
* Update referrers to _oras/artifacts/referrers
* Renamed response property to referrers

Signed-off-by: Sajay Antony <[email protected]>
  • Loading branch information
@sajayantony
sajayantony authored Jan 18, 2022
1 parent df0311a commit e853018
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 29 deletions.
2 changes: 1 addition & 1 deletion docs/quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ A quick-start for push, discover, pull
oras discover \
-o json \
--artifact-type sbom/example \
$IMAGE | jq -r ".references[0].digest")
$IMAGE | jq -r ".referrers[0].digest")
```

## Further Reading
Expand Down
73 changes: 45 additions & 28 deletions manifest-referrers-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,43 @@
[Artifact-manifest](./artifact-manifest.md) provides the ability to reference artifacts to existing artifacts.
Reference artifacts include signatures, SBoMs and many other types.
Artifacts that reference other artifacts SHOULD NOT be tagged, as they are considered enhancements to the artifacts they reference.
To discover referenced artifacts a manifest `referrers/` API is provided.
An artifact client would parse the returned [artifact descriptors][descriptor], determining which `artifact.manifest` they will pull and process.
The `referrers` extension API is provided to discover these artifacts.
An artifact client would parse the returned [artifact descriptors][descriptor], determining which artifact manifest they will pull and process.

The `referrers/` API returns all artifacts that have a `subject` to given manifest digest.
Referenced artifact requests are scoped to a repository, ensuring access rights for the repository can be used as authorization for the referenced artifacts.
The `referrers` API returns all artifacts that have a `subject` of the given manifest digest.
Reference artifact requests are scoped to a repository, ensuring access rights for the repository can be used as authorization for the referenced artifacts.

Artifact references are defined in the [artifact-manifest][oras.artifact.manifest-spec] spec through the [`subject`][oras.artifact.manifest-spec-manifests] property.

## API Path

The `referrers/` api is sits alongside the [distribution-spec][oci-distribution-spec] paths avoiding conflict with existing or new distribution spec apis.
Pathing within the referrers api provides consistent namespace/repo paths, enabling registry operators to implement consistent auth access, using existing tokens for content.
The `referrers` api are provided on the [distribution-spec][oci-distribution-spec] paths as described below.
Pathing of the referrers api provides consistent namespace/repository paths, enabling registry operators to implement consistent auth access, using existing tokens for content.

**template:**

```rest
GET /oras/artifacts/v1/{repository}/manifests/{digest}/referrers
GET /v2/{repository}/_oras/artifacts/referrers?digest={digest}
```

**expanded example:**

```rest
GET /oras/artifacts/v1/net-monitor/manifests/sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b/referrers
GET /v2/net-monitor/_oras/artifacts/referrers?digest=sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b
```

## Versioning

This spec defines the behavior of the `/oras/artifacts/v1` version. Clients MUST account for version checking as future major versions MAY NOT be compatible.
Future Minor versions MUST be additive.
This specification defines the versioning behavior of `_oras/artifacts/referrers` API.
Implementations SHOULD return `ORAS-Api-Version: oras/1.0`. Clients MUST account
for version checking as future major versions MAY NOT be compatible. Future minor
versions MUST be additive.

```http
GET /v2/<repository>/_oras/artifacts/referrers?digest={digest}
...
ORAS-Api-Version: oras/1.0
```

## Artifact Referrers API results

Expand All @@ -47,14 +55,16 @@ In future versioned releases, responses MAY be extended to include a `data` fiel

This paged result MUST return the following elements:

- `references`: A list of [artifact descriptors][descriptor] that reference the given manifest. The list MUST include
these references even if the given manifest does not exist in the repository. The list MUST be empty
- `referrers`: A list of [artifact descriptors][descriptor] that reference the
given manifest. The list MUST include these references even if the given
manifest does not exist in the repository. The list MUST be empty
if there are no artifacts referencing the given manifest.

**example result of artifacts that reference the `net-monitor` image:**

```json
{
"references": [
"referrers": [
{
"digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b",
"mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json",
Expand All @@ -72,43 +82,45 @@ if there are no artifacts referencing the given manifest.
```

**example result for a manifest that has no artifacts referencing it:**

```json
{
"references": []
"referrers": []
}
```

### Paging Results

The `/referrers` API MUST provide for paging, returning a list of [artifact descriptors](./descriptor.md).
The `referrers` API MUST provide for paging, returning a list of [artifact descriptors](./descriptor.md).
Page size can be specified by adding a `n` parameter to the request URL, indicating that the response should be limited to `n` results.

* If specified, servers MAY return up to `n` items from the entire result set.
* When `n` is not provided, servers MAY return a default number of items, which may be implementation specific.
- If specified, servers MAY return up to `n` items from the entire result set.
- When `n` is not provided, servers MAY return a default number of items, which may be implementation specific.

A paginated flow begins as:

**template:**

```rest
GET /oras/artifacts/v1/{repository}/manifests/{digest}/referrers?n=<integer>
GET /v2/{repository}/_oras/artifacts/referrers?digest={digest}&n=<integer>
```

**expanded example:**

```rest
GET /oras/artifacts/v1/net-monitor/manifests/sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b/referrers?n=10
GET /v2/{repository}/_oras/artifacts/referrers?digest=sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b&n=10
```

The above specifies that a referrers response should be returned limiting the number of results to `n`. There is no
ordering imposed on the resulting collection. The response to such a request would look as follows:

```json
200 OK
ORAS-Api-Version:oras/1.0
Link: <url>; rel="next"

{
"references": [
"referrers": [
{
"digest": "<string>",
"mediaType": "<string>",
Expand All @@ -124,40 +136,45 @@ The above includes up to `n` items from the result set. If there are more items,
encoded in a [RFC5988][rfc5988] `Link` header, as a "next" relation. Clients SHOULD treat this as an opaque value and not try to
construct it themselves.

* The presence of the `Link` header communicates to the client that the server has more items. Clients are expected
- The presence of the `Link` header communicates to the client that the server has more items. Clients are expected
to follow the link to fetch the next page of items, irrespective of the number of items received in the current
response.
* If the header is not present, clients can assume that all items have been received.
- If the header is not present, clients can assume that all items have been received.

> NOTE: In the request template above, the brackets around the url are required.
> NOTE: In the request template above, the brackets around the url are required.
For example, if the url is:

```
http://example.com/oras/artifacts/v1/hello-world/manifests/sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b/referrers?n=5&nextToken=abc
http://example.com/v2/hello-world/_oras/artifacts/referrers?digest=sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b&n=5&nextToken=abc
```

The value of the header would be:

```
<http://example.com/oras/artifacts/v1/hello-world/manifests/sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b/referrers?n=5&nextToken=abc>; rel="next"`.
<http://example.com/v2/hello-world/_oras/artifacts/referrers?digest=sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b&n=5&nextToken=abc>; rel="next"`.
```

Please see [RFC5988][rfc5988] for details.

### Filtering Results

The `/referrers` API MAY provide for filtering of `artifactTypes`.
The `referrers` API MAY provide for filtering of `artifactTypes`.
Artifact clients MUST account for implementations that MAY NOT support filtering.
Artifact clients MUST revert to client side filtering to determine which `artifactTypes` they will process.

Request referenced artifacts by `artifactType`

**template:**

```rest
GET /oras/artifacts/v1/{repository}/manifests/{digest}/referrers?n=10&artifactType={artifactType}
GET /v2/{repository}/_oras/artifacts/referrers?digest={digest}&n=10&artifactType={artifactType}
```

**expanded example:**

```rest
GET /oras/artifacts/v1/net-monitor/manifests/sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b/referrers?n=10&artifactType=signature%2Fexample
GET /v2/net-monitor/_oras/artifacts/referrers?digest=sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b&n=10&artifactType=signature%2Fexample
```

## Further Reading
Expand Down

0 comments on commit e853018

Please sign in to comment.