diff --git a/extensions/_oci.md b/extensions/_oci.md index 1ae44e2b..e5f6abf2 100644 --- a/extensions/_oci.md +++ b/extensions/_oci.md @@ -66,6 +66,105 @@ Content-Type: application/json Enumeration of the endpoints provided on this registry (as not all "OPTIONAL" endpoints may be present in all registries) +### Component: `repositories` + +This component is for endpoints relating to repository listing operations. + +This endpoint returns repositories under a namespace path, in lexical (i.e. case-insensitive alphanumeric order) or "ASCIIbetical" ([Go's `sort.Strings`](https://pkg.go.dev/sort#Strings)) order. + +Repository listing MAY be retrieved with a standard `GET` as follows. + +```HTTP +GET /v2//_oci/repositories +``` + +Registry implementations MAY allow `` to be empty in order to list all repositories available on the registry. +When `` is empty, the path is: + +```HTTP +GET /v2/_oci/repositories +``` + +A registry that does not support listing repositories with an empty `` MUST return a `405 Method Not Allowed` response code for this request. + +When non-empty, `` is a `/` delimited repository namespace path. +For this endpoint, a non-empty `` is used as a namespace segment prefix and MUST include one or more complete namespace segments. +For requests with a non-empty ``, returned repositories MUST have names that are equal to `` or that begin with `/`. +Registries MUST NOT treat a non-empty `` as a partial namespace segment prefix. +For example, given repositories `foo/bar`, `foo/baz`, and `bar/baz`, a request to `/v2/foo/_oci/repositories` returns `foo/bar` and `foo/baz`. + +A successful request MUST return a `200 OK` response code. +If the namespace path is invalid or the registry cannot list repositories under it, the registry MUST return an appropriate error response. +The list of repositories MAY be empty if there are no repositories under the namespace path. +Registry implementations MAY limit the repositories returned based on implementation policy, access control, or other registry-specific behavior. +The presence of a repository in the response only indicates that the registry may provide access to that repository at the time of the request. +The absence of a repository from the response does not indicate that the repository does not exist. + +Upon success, the response body MUST be a JSON array of repository objects in the following format: + +```HTTP +200 OK +Content-Length: +Content-Type: application/json + +[ + { + "name": "foo/bar" + }, + { + "name": "foo/baz" + } +] +``` + +Each repository object in the response MUST include the following properties: + +- **`name`** *string*, OPTIONAL + + The full repository name. + The value MUST match the repository name syntax defined for `` in this specification. + The value MUST be equal to the requested namespace path or have the requested namespace path as a complete namespace segment prefix. + +Repository objects MAY include additional properties. + +##### Query Parameters + +The following query parameters MAY be provided: + +- **`n`** *integer*, OPTIONAL + + Specifies the maximum number of results to return. + The registry MAY return fewer results than requested if fewer matching repositories exist or a `Link` header is provided. + Otherwise, the response MUST include `n` results. + When `n` is zero, this endpoint MUST return an empty array and MUST NOT include a `Link` header. + When `n` is not specified, the registry MAY apply a default limit. + +- **`last`** *string*, OPTIONAL + + Specifies the `name` value of the last repository object received by the client. + When provided, the response MUST begin non-inclusively after `last` in the ordered repository list. + The `last` value MUST NOT be a numerical index. + When using the `last` query parameter, the `n` parameter is OPTIONAL. + +A `Link` header MAY be included in the response when additional repositories are available. +If included, the `Link` header MUST be set according to [RFC5988](https://www.rfc-editor.org/rfc/rfc5988.html) with the Relation Type `rel="next"`. + +##### Pagination Example + +To fetch the first page of up to 10 repositories: + +```HTTP +GET /v2//_oci/repositories?n=10 +``` + +To fetch the next page, pass the `name` value of the last repository object from the prior response as the `last` parameter: + +```HTTP +GET /v2//_oci/repositories?n=10&last=foo/bar +``` + +When a `Link` header is provided, clients SHOULD prefer the `Link` header over constructing the next request with the `last` parameter. + ## Code representations Golang structures for these JSON structures is available at [`github.com/opencontainers/distribution-spec/specs-go/v1/extensions`](https://github.com/opencontainers/distribution-spec/tree/main/specs-go/v1/extensions/)