You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Enumeration of the endpoints provided on this registry (as not all "OPTIONAL" endpoints may be present in all registries)
68
68
69
+
### Component: `repositories`
70
+
71
+
This component is for endpoints relating to repository listing operations.
72
+
73
+
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.
74
+
75
+
Repository listing MAY be retrieved with a standard `GET` as follows.
76
+
77
+
```HTTP
78
+
GET /v2/<name>/_oci/repositories
79
+
```
80
+
81
+
Registry implementations MAY allow `<name>` to be empty in order to list all repositories available on the registry.
82
+
When `<name>` is empty, the path is:
83
+
84
+
```HTTP
85
+
GET /v2/_oci/repositories
86
+
```
87
+
88
+
A registry that does not support listing repositories with an empty `<name>` MUST return a `405 Method Not Allowed` response code for this request.
89
+
90
+
When non-empty, `<name>` is a `/` delimited repository namespace path.
91
+
For this endpoint, a non-empty `<name>` is used as a namespace segment prefix and MUST include one or more complete namespace segments.
92
+
For requests with a non-empty `<name>`, returned repositories MUST have names that are equal to `<name>` or that begin with `<name>/`.
93
+
Registries MUST NOT treat a non-empty `<name>` as a partial namespace segment prefix.
94
+
For example, given repositories `foo/bar`, `foo/baz`, and `bar/baz`, a request to `/v2/foo/_oci/repositories` returns `foo/bar` and `foo/baz`.
95
+
96
+
A successful request MUST return a `200 OK` response code.
97
+
If the namespace path is invalid or the registry cannot list repositories under it, the registry MUST return an appropriate error response.
98
+
The list of repositories MAY be empty if there are no repositories under the namespace path.
99
+
Registry implementations MAY limit the repositories returned based on implementation policy, access control, or other registry-specific behavior.
100
+
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.
101
+
The absence of a repository from the response does not indicate that the repository does not exist.
102
+
103
+
Upon success, the response body MUST be a JSON array of repository objects in the following format:
104
+
105
+
```HTTP
106
+
200 OK
107
+
Content-Length: <length>
108
+
Content-Type: application/json
109
+
110
+
[
111
+
{
112
+
"name": "foo/bar"
113
+
},
114
+
{
115
+
"name": "foo/baz"
116
+
}
117
+
]
118
+
```
119
+
120
+
Each repository object in the response MUST include the following properties:
121
+
122
+
-**`name`***string*, OPTIONAL
123
+
124
+
The full repository name.
125
+
The value MUST match the repository name syntax defined for `<name>` in this specification.
126
+
The value MUST be equal to the requested namespace path or have the requested namespace path as a complete namespace segment prefix.
127
+
128
+
Repository objects MAY include additional properties.
129
+
130
+
##### Query Parameters
131
+
132
+
The following query parameters MAY be provided:
133
+
134
+
-**`n`***integer*, OPTIONAL
135
+
136
+
Specifies the maximum number of results to return.
137
+
The registry MAY return fewer results than requested if fewer matching repositories exist or a `Link` header is provided.
138
+
Otherwise, the response MUST include `n` results.
139
+
When `n` is zero, this endpoint MUST return an empty array and MUST NOT include a `Link` header.
140
+
When `n` is not specified, the registry MAY apply a default limit.
141
+
142
+
-**`last`***string*, OPTIONAL
143
+
144
+
Specifies the `name` value of the last repository object received by the client.
145
+
When provided, the response MUST begin non-inclusively after `last` in the ordered repository list.
146
+
The `last` value MUST NOT be a numerical index.
147
+
When using the `last` query parameter, the `n` parameter is OPTIONAL.
148
+
149
+
A `Link` header MAY be included in the response when additional repositories are available.
150
+
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"`.
151
+
152
+
##### Pagination Example
153
+
154
+
To fetch the first page of up to 10 repositories:
155
+
156
+
```HTTP
157
+
GET /v2/<name>/_oci/repositories?n=10
158
+
```
159
+
160
+
To fetch the next page, pass the `name` value of the last repository object from the prior response as the `last` parameter:
161
+
162
+
```HTTP
163
+
GET /v2/<name>/_oci/repositories?n=10&last=foo/bar
164
+
```
165
+
166
+
When a `Link` header is provided, clients SHOULD prefer the `Link` header over constructing the next request with the `last` parameter.
167
+
69
168
## Code representations
70
169
71
170
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/)
0 commit comments