Update spec to include repository endpoint#611
Conversation
Signed-off-by: Jeff Carter <jeff.carter@docker.com>
jcarter3
force-pushed
the
repository-listing
branch
from
7be79d4 to
2fec3d1
Compare
sudo-bmitch
left a comment
sudo-bmitch
left a comment
There was a problem hiding this comment.
Just a first pass. As with the tag listing, I'm going to want to spend some time implementing it and see a conformance test before approving.
| Repository listing MAY be retrieved with a standard `GET` as follows. | ||
|
|
||
| ```HTTP | ||
| GET /v2/<name>/_oci/repositories |
There was a problem hiding this comment.
To follow the _extension/module/component syntax, perhaps:
| GET /v2/<name>/_oci/repositories | |
| GET /v2/<name>/_oci/repository/list |
| When `<name>` is empty, the path is: | ||
|
|
||
| ```HTTP | ||
| GET /v2/_oci/repositories |
There was a problem hiding this comment.
| GET /v2/_oci/repositories | |
| GET /v2/_oci/repository/list |
| GET /v2/_oci/repositories | ||
| ``` | ||
|
|
||
| A registry that does not support listing repositories with an empty `<name>` MUST return a `405 Method Not Allowed` response code for this request. |
There was a problem hiding this comment.
Shouldn't it be 404, same as a registry that doesn't implement the extension? I'd also consider "SHOULD" since implementations are really good at throwing other 4xx codes, along with the occasional 5xx. We'd like registries to be consistent, but clients should be prepared for a wild west.
|
|
||
| A registry that does not support listing repositories with an empty `<name>` MUST return a `405 Method Not Allowed` response code for this request. | ||
|
|
||
| When non-empty, `<name>` is a `/` delimited repository namespace path. |
There was a problem hiding this comment.
Perhaps we should say <prefix> or some other term since <name> is used throughout the spec to refer to the full namespace path.
| For this endpoint, a non-empty `<name>` is used as a namespace segment prefix and MUST include one or more complete namespace segments. | ||
| For requests with a non-empty `<name>`, returned repositories MUST have names that are equal to `<name>` or that begin with `<name>/`. | ||
| Registries MUST NOT treat a non-empty `<name>` 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`. |
There was a problem hiding this comment.
To make it clear the segments must be complete, I'd include a matching partial segment:
| For example, given repositories `foo/bar`, `foo/baz`, and `bar/baz`, a request to `/v2/foo/_oci/repositories` returns `foo/bar` and `foo/baz`. | |
| For example, given repositories `foo/bar`, `foo/baz`, and `foobar/baz`, a request to `/v2/foo/_oci/repositories` returns `foo/bar` and `foo/baz`. |
| 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. |
There was a problem hiding this comment.
We should list the expected error response codes. I'm expecting 400, 401, 403, and 404 to all be expected errors to cover invalid prefix, not found prefix, unauthorized, and extension not implemented.
| The value MUST match the repository name syntax defined for `<name>` 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. |
There was a problem hiding this comment.
| Repository objects MAY include additional properties. | |
| Repository objects MAY include additional properties. | |
| Field order and whitespace may vary by implementation. |
| - **`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"`. |
There was a problem hiding this comment.
I'm sure the pagination was pulled from the tag listing. I think there's debate on whether the Link header or the last parameter should be used, and for historical reasons we ended up needing to document/support both. For a green field API, we have an opportunity to pick a single pagination option, and I'd probably lean towards the Link header for that. Then we could remove the n and last parameters.
2 participants
Throwing out a proposal to replace/enhance _catalog