Skip to content

Commit bd06a13

Browse files
CollinShoopCollin Shoop
CollinShoop
and
Collin Shoop
authored
registry/CON-3906: Added documnentation for new registry/http endpoints: ListRepositoriesV2 and ListManifests (#567)
* registry/CON-3907: Added documnentation for new registry/http endpoints: ListRepositoriesV2 and ListManifests * registry: Deprecated ListRegistryRepositories endpoint. Co-authored-by: Collin Shoop <[email protected]>
1 parent b60703b commit bd06a13

14 files changed

+337
-4
lines changed

‎specification/DigitalOcean-public.v2.yaml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1124,10 +1124,14 @@ paths:
11241124
post:
11251125
$ref: 'resources/registry/validate_registry_name.yml'
11261126

1127-
/v2/registry/{registry_name}:
1127+
/v2/registry/{registry_name}/repositories:
11281128
get:
11291129
$ref: 'resources/registry/list_registry_repositories.yml'
11301130

1131+
/v2/registry/{registry_name}/repositoriesV2:
1132+
get:
1133+
$ref: 'resources/registry/list_registry_repositories_v2.yml'
1134+
11311135
/v2/registry/{registry_name}/{repository_name}/tags:
11321136
get:
11331137
$ref: 'resources/registry/list_repository_tags.yml'
@@ -1136,6 +1140,10 @@ paths:
11361140
delete:
11371141
$ref: 'resources/registry/delete_repository_tag.yml'
11381142

1143+
/v2/registry/{registry_name}/{repository_name}/digests:
1144+
get:
1145+
$ref: 'resources/registry/list_repository_manifests.yml'
1146+
11391147
/v2/registry/{registry_name}/{repository_name}/digests/{manifest_digest}:
11401148
delete:
11411149
$ref: 'resources/registry/delete_repository_manifest.yml'

‎specification/resources/registry/examples/curl/list_registry_repositories_v2.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
lang: cURL
2+
source: |-
3+
curl -X GET \
4+
-H "Content-Type: application/json" \
5+
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
6+
"https://api.digitalocean.com/v2/registry/example/repositoriesV2?page_size=1"

‎specification/resources/registry/examples/curl/list_registry_repositories_v2_next_page.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
lang: cURL (next page)
2+
source: |-
3+
curl -X GET \
4+
-H "Content-Type: application/json" \
5+
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
6+
"https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=2&page_token=JPZmZzZXQiOjB9&per_page=1"

‎specification/resources/registry/examples/curl/list_repository_manifests.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
lang: cURL
2+
source: |-
3+
curl -X GET \
4+
-H "Content-Type: application/json" \
5+
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
6+
"https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests"

‎specification/resources/registry/list_registry_repositories.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,16 @@
11
operationId: list_registry_repositories
22

3+
deprecated: true
4+
35
summary: List All Container Registry Repositories
46

5-
description: To list all repositories in your container registry, send a GET
7+
description: |
8+
This endpoint has been deprecated in favor of the _List All Container Registry Repositories [V2]_ endpoint.
9+
10+
To list all repositories in your container registry, send a GET
611
request to `/v2/registry/$REGISTRY_NAME/repositories`.
712
13+
814
tags:
915
- Container Registry
1016

‎specification/resources/registry/list_registry_repositories_v2.yml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
operationId: list_registry_repositories_v2
2+
3+
summary: List All Container Registry Repositories (V2)
4+
5+
description: To list all repositories in your container registry, send a GET
6+
request to `/v2/registry/$REGISTRY_NAME/repositoriesV2`.
7+
8+
tags:
9+
- Container Registry
10+
11+
parameters:
12+
- $ref: '../../shared/parameters.yml#/per_page'
13+
- $ref: 'parameters.yml#/token_pagination_page'
14+
- $ref: 'parameters.yml#/token_pagination_page_token'
15+
- $ref: 'parameters.yml#/registry_name'
16+
17+
responses:
18+
'200':
19+
$ref: 'responses/all_repositories_v2.yml'
20+
21+
'400':
22+
$ref: '../../shared/responses/bad_request.yml'
23+
24+
'401':
25+
$ref: '../../shared/responses/unauthorized.yml'
26+
27+
'404':
28+
$ref: '../../shared/responses/not_found.yml'
29+
30+
'429':
31+
$ref: '../../shared/responses/too_many_requests.yml'
32+
33+
'500':
34+
$ref: '../../shared/responses/server_error.yml'
35+
36+
default:
37+
$ref: '../../shared/responses/unexpected_error.yml'
38+
39+
x-codeSamples:
40+
- $ref: 'examples/curl/list_registry_repositories_v2.yml'
41+
- $ref: 'examples/curl/list_registry_repositories_v2_next_page.yml'

‎specification/resources/registry/list_repository_manifests.yml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
operationId: list_repository_digests
2+
3+
summary: List All Container Registry Repository Manifests
4+
5+
description: |
6+
To list all manifests in your container registry repository, send a GET
7+
request to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests`.
8+
9+
Note that if your repository name contains `/` characters, it must be
10+
URL-encoded in the request URL. For example, to list manifests for
11+
`registry.digitalocean.com/example/my/repo`, the path would be
12+
`/v2/registry/example/repositories/my%2Frepo/digests`.
13+
14+
tags:
15+
- Container Registry
16+
17+
parameters:
18+
- $ref: '../../shared/parameters.yml#/per_page'
19+
- $ref: '../../shared/parameters.yml#/page'
20+
- $ref: 'parameters.yml#/registry_name'
21+
- $ref: 'parameters.yml#/registry_repository_name'
22+
23+
responses:
24+
'200':
25+
$ref: 'responses/repository_manifests.yml'
26+
27+
'401':
28+
$ref: '../../shared/responses/unauthorized.yml'
29+
30+
'404':
31+
$ref: '../../shared/responses/not_found.yml'
32+
33+
'429':
34+
$ref: '../../shared/responses/too_many_requests.yml'
35+
36+
'500':
37+
$ref: '../../shared/responses/server_error.yml'
38+
39+
default:
40+
$ref: '../../shared/responses/unexpected_error.yml'
41+
42+
x-codeSamples:
43+
- $ref: 'examples/curl/list_repository_manifests.yml'

‎specification/resources/registry/models/repository_blob.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
type: object
2+
3+
properties:
4+
5+
digest:
6+
type: string
7+
example: sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
8+
description: The digest of the blob
9+
10+
compressed_size_bytes:
11+
type: integer
12+
example: 2803255
13+
description: The compressed size of the blob in bytes.

‎specification/resources/registry/models/repository_manifest.yml

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
type: object
2+
3+
properties:
4+
registry_name:
5+
type: string
6+
example: example
7+
description: The name of the container registry.
8+
9+
repository:
10+
type: string
11+
example: repo-1
12+
description: The name of the repository.
13+
14+
digest:
15+
type: string
16+
example: sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
17+
description: The manifest digest
18+
19+
compressed_size_bytes:
20+
type: integer
21+
example: 2803255
22+
description: The compressed size of the manifest in bytes.
23+
24+
size_bytes:
25+
type: integer
26+
example: 5861888
27+
description: The uncompressed size of the manifest in bytes (this size is
28+
calculated asynchronously so it may not be immediately available).
29+
30+
updated_at:
31+
type: string
32+
format: date-time
33+
example: '2020-04-09T23:54:25Z'
34+
description: The time the manifest was last updated.
35+
36+
tags:
37+
type: array
38+
items:
39+
type: string
40+
example:
41+
- latest
42+
- v1
43+
- v2
44+
description: All tags associated with this manifest
45+
46+
blobs:
47+
type: array
48+
items:
49+
$ref: 'repository_blob.yml'
50+
description: All blobs associated with this manifest

‎specification/resources/registry/models/repository_tag.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ properties:
66
example: example
77
description: The name of the container registry.
88

9-
repository_name:
9+
repository:
1010
type: string
1111
example: repo-1
1212
description: The name of the repository.

‎specification/resources/registry/models/repository_v2.yml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
type: object
2+
3+
properties:
4+
registry_name:
5+
type: string
6+
example: example
7+
description: The name of the container registry.
8+
9+
name:
10+
type: string
11+
example: repo-1
12+
description: The name of the repository.
13+
14+
latest_manifest:
15+
$ref: 'repository_manifest.yml'
16+
17+
tag_count:
18+
type: integer
19+
example: 1
20+
description: The number of tags in the repository.
21+
22+
manifest_count:
23+
type: integer
24+
example: 1
25+
description: The number of manifests in the repository.

‎specification/resources/registry/parameters.yml

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,4 +65,24 @@ garbage_collection_uuid:
6565
required: true
6666
schema:
6767
type: string
68-
example: eff0feee-49c7-4e8f-ba5c-a320c109c8a8
68+
example: eff0feee-49c7-4e8f-ba5c-a320c109c8a8
69+
70+
token_pagination_page:
71+
in: query
72+
name: page
73+
required: false
74+
description: Which 'page' of paginated results to return. Ignored when 'page_token' is provided.
75+
schema:
76+
type: integer
77+
minimum: 1
78+
default: 1
79+
example: 1
80+
81+
token_pagination_page_token:
82+
in: query
83+
name: page_token
84+
required: false
85+
description: Token to retrieve of the next or previous set of results more quickly than using 'page'.
86+
schema:
87+
type: string
88+
example: eyJUb2tlbiI6IkNnZGpiMjlz

‎specification/resources/registry/responses/all_repositories_v2.yml

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
description: The response body will be a JSON object with a key of
2+
`repositories`. This will be set to an array containing objects each
3+
representing a repository.
4+
5+
headers:
6+
ratelimit-limit:
7+
$ref: '../../../shared/headers.yml#/ratelimit-limit'
8+
ratelimit-remaining:
9+
$ref: '../../../shared/headers.yml#/ratelimit-remaining'
10+
ratelimit-reset:
11+
$ref: '../../../shared/headers.yml#/ratelimit-reset'
12+
13+
content:
14+
application/json:
15+
schema:
16+
allOf:
17+
- type: object
18+
properties:
19+
repositories:
20+
type: array
21+
items:
22+
$ref: '../models/repository_v2.yml'
23+
- $ref: '../../../shared/pages.yml#/pagination'
24+
- $ref: '../../../shared/meta.yml'
25+
26+
example:
27+
repositories:
28+
- registry_name: example
29+
name: repo-1
30+
tag_count: 57
31+
manifest_count: 82
32+
latest_manifest:
33+
digest: sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
34+
registry_name: example
35+
repository: repo-1
36+
compressed_size_bytes: 1972332
37+
size_bytes: 2816445
38+
updated_at: '2021-04-09T23:54:25Z'
39+
tags:
40+
- v1
41+
- v2
42+
blobs:
43+
- digest: sha256:14119a10abf4669e8cdbdff324a9f9605d99697215a0d21c360fe8dfa8471bab
44+
compressed_size_bytes: 1471
45+
- digest: sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e
46+
compressed_size_byte: 2814446
47+
- digest: sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a
48+
compressed_size_bytes: 528
49+
meta:
50+
total: 5
51+
links:
52+
pages:
53+
next: https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=2&page_token=JPZmZzZXQiOjB9&per_page=1
54+
last: https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=5&per_page=1

‎specification/resources/registry/responses/repository_manifests.yml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
description: The response body will be a JSON object with a key of `manifests`. This
2+
will be set to an array containing objects each representing a manifest.
3+
4+
headers:
5+
ratelimit-limit:
6+
$ref: '../../../shared/headers.yml#/ratelimit-limit'
7+
ratelimit-remaining:
8+
$ref: '../../../shared/headers.yml#/ratelimit-remaining'
9+
ratelimit-reset:
10+
$ref: '../../../shared/headers.yml#/ratelimit-reset'
11+
12+
content:
13+
application/json:
14+
schema:
15+
allOf:
16+
- type: object
17+
properties:
18+
manifests:
19+
type: array
20+
items:
21+
$ref: '../models/repository_manifest.yml'
22+
- $ref: '../../../shared/pages.yml#/pagination'
23+
- $ref: '../../../shared/meta.yml'
24+
example:
25+
manifests:
26+
- digest: sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
27+
registry_name: example
28+
repository: repo-1
29+
compressed_size_bytes: 1972332
30+
size_bytes: 2816445
31+
updated_at: '2021-04-09T23:54:25Z'
32+
tags:
33+
- v1
34+
- v2
35+
blobs:
36+
- digest: sha256:14119a10abf4669e8cdbdff324a9f9605d99697215a0d21c360fe8dfa8471bab
37+
compressed_size_bytes: 1471
38+
- digest: sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e
39+
compressed_size_byte: 2814446
40+
- digest: sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a
41+
compressed_size_bytes: 528
42+
meta:
43+
total: 3
44+
links:
45+
pages:
46+
first: >-
47+
https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=1&per_page=1
48+
prev: >-
49+
https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=1&per_page=1
50+
next: >-
51+
https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=3&per_page=1
52+
last: >-
53+
https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=3&per_page=1
54+
55+

0 commit comments

Comments
 (0)