docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #15154 from technicallyjosh/master 

Refactor formatting and fix validation
This commit is contained in:
jerae-duffin 2022-07-19 11:15:35 -05:00 committed by GitHub
parent bafe941f2d 32e64ce12c
commit 927cf1eb4f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 166 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

397
docker-hub/api/latest.yaml
View File

@ -5,7 +5,7 @@ info:
x-logo:
url: https://docs.docker.com/images/logo-docker-main.png
href: /reference
description: >
description: |
Docker Hub is a service provided by Docker for finding and sharing container
images with your team.
@ -19,43 +19,28 @@ info:
tags:
- name: resources
x-displayName: Resources
description: >
description: |
The following resources are available to interact with the documented API:
- <a href="https://github.com/docker/hub-tool#readme" target="_blank">Docker Hub CLI tool</a> (currently experimental)
- <a href="https://www.postman.com/dockerdev/workspace/docker-hub/collection/17990590-9574e087-2a50-4ecf-88b3-55f12a29d99e" target="_blank">Postman Collection</a>
- name: rate-limiting
x-displayName: Rate Limiting
description: >
The Docker Hub API is limited on the amount of requests you can perform
per minute against it.
description: |
The Docker Hub API is limited on the amount of requests you can perform per minute against it.
If you haven't hit the limit, each request to the API will return the
following headers in the response.
- `X-RateLimit-Limit` - The limit of requests per minute.
- `X-RateLimit-Remaining` - The remaining amount of calls within the limit
period.
- `X-RateLimit-Remaining` - The remaining amount of calls within the limit period.
- `X-RateLimit-Reset` - The unix timestamp of when the remaining resets.
If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After`
header in the response.
If you have hit the limit, you will receive a response status of `429` and
the `X-Retry-After` header in the response.
The `X-Retry-After` header is a unix timestamp of when you can call the
API again.
The `X-Retry-After` header is a unix timestamp of when you can call the API again.
*Note: These rate limits are separate from anti-abuse and Docker Hub
@ -64,72 +49,55 @@ tags:
limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/).*
- name: authentication
x-displayName: Authentication
description: >
description: |
Most Docker Hub API endpoints require you to authenticate using your
Docker credentials before using them.
Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Free, Pro, or Team) and your account's permissions.
Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending
on your plan (Free, Pro, or Team) and your account's permissions.
To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing).
- name: access-tokens
x-displayName: Personal Access Tokens
description: >
The Personal Access Token endpoints lets you manage personal access
tokens. For more information, see
[Access Tokens](https://docs.docker.com/docker-hub/access-tokens/).
You can use a personal access token instead of a password in the
[Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or
in the [Create an authentication token](#operation/PostUsersLogin) route
to obtain a bearer token.
description: |
The Personal Access Token endpoints lets you manage personal access tokens. For more
information, see [Access Tokens](https://docs.docker.com/docker-hub/access-tokens/).
You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/)
or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer
token.
### Scopes
For each scope grouping (in this case "repo"), you only need to define 1
scope as any lower scopes are assumed. For example: If you define
`repo:write`, the API assumes the scope of both `repo:read` *and*
`repo:public_read` as well. If you were to define both `repo:write` *and*
For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower
scopes are assumed. For example: If you define `repo:write`, the API assumes the scope of both
`repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and*
`repo:read`, then `repo:read` is assumed by `repo:write` and ignored.
***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after
it is generated.***
***Treat your personal access token like your password and keep it secret. You cannot retrieve
your token after it is generated.***
- name: images
x-displayName: Advanced Image Management
description: >
description: |
The Advanced Image Management API endpoints allow you to manage Docker
images across all repositories.
For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/).
- name: audit-logs
x-displayName: Audit Logs
description: >
description: |
The Audit Logs API endpoints allow you to query audit log events across a
namespace.
For more information, see [Audit Log](https://docs.docker.com/docker-hub/audit-log/)
- name: org-settings
x-displayName: Org Settings
description: >
description: |
The Org Settings API endpoints allow you to manage your organization's
settings.
- name: repositories
x-displayName: Repositories
description: >
description: |
The repository endpoints allow you to manage your repository's
configuration like description.
x-tagGroups:
@ -152,14 +120,12 @@ paths:
- authentication
summary: Create an authentication token
operationId: PostUsersLogin
description: >
description: |
Creates and returns a bearer token in JWT format that you can use to
authenticate with Docker Hub APIs.
The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
requestBody:
content:
@ -169,13 +135,13 @@ paths:
description: Login details.
required: true
responses:
"200":
200:
description: Authentication successful
content:
application/json:
schema:
$ref: "#/components/schemas/PostUsersLoginSuccessResponse"
"401":
401:
description: Authentication failed or second factor required
content:
application/json:
@ -187,17 +153,14 @@ paths:
- authentication
summary: Second factor authentication.
operationId: PostUsers2FALogin
description: >
description: |
When user has 2FA enabled, this is the second call to perform after
`/v2/users/login` call.
Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.
The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
requestBody:
content:
@ -207,13 +170,13 @@ paths:
description: Login details.
required: true
responses:
"200":
200:
description: Authentication successful
content:
application/json:
schema:
$ref: "#/components/schemas/PostUsersLoginSuccessResponse"
"401":
401:
description: Authentication failed or second factor required
content:
application/json:
@ -232,15 +195,15 @@ paths:
$ref: "#/components/schemas/createAccessTokenRequest"
required: true
responses:
"201":
201:
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/createAccessTokensResponse"
"400":
400:
$ref: "#/components/responses/BadRequest"
"401":
401:
$ref: "#/components/responses/Unauthorized"
get:
summary: Get a list of personal access tokens
@ -259,17 +222,23 @@ paths:
type: number
default: 10
responses:
"200":
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/getAccessTokensResponse"
"400":
400:
$ref: "#/components/responses/BadRequest"
"401":
401:
$ref: "#/components/responses/Unauthorized"
"/v2/access-tokens/{uuid}":
/v2/access-tokens/{uuid}:
parameters:
- in: path
name: uuid
required: true
schema:
type: string
patch:
summary: Update a personal access token
description: |
@ -277,12 +246,6 @@ paths:
token's label or enable/disable it.
tags:
- access-tokens
parameters:
- in: path
name: uuid
required: true
schema:
type: string
requestBody:
content:
application/json:
@ -290,15 +253,15 @@ paths:
$ref: "#/components/schemas/patchAccessTokenRequest"
required: true
responses:
"200":
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/patchAccessTokenResponse"
"400":
400:
$ref: "#/components/responses/BadRequest"
"401":
401:
$ref: "#/components/responses/Unauthorized"
get:
summary: Get a personal access token
@ -306,7 +269,7 @@ paths:
tags:
- access-tokens
responses:
"200":
200:
description: OK
content:
application/json:
@ -318,9 +281,9 @@ paths:
token:
type: string
example: ""
"401":
401:
$ref: "#/components/responses/Unauthorized"
"404":
404:
$ref: "#/components/responses/NotFound"
delete:
summary: Delete a personal access token
@ -328,25 +291,19 @@ paths:
Deletes a personal access token permanently. This cannot be undone.
tags:
- access-tokens
parameters:
- in: path
name: uuid
required: true
schema:
type: string
responses:
"204":
204:
description: A successful response.
"401":
401:
$ref: "#/components/responses/Unauthorized"
"404":
404:
$ref: "#/components/responses/NotFound"
"/v2/namespaces/{namespace}/repositories/{repository}/images-summary":
/v2/namespaces/{namespace}/repositories/{repository}/images-summary:
get:
tags:
- images
summary: Get summary of repository's images
description: >
description: |
Gets the number of images in a repository and the number of images
counted as active and inactive.
operationId: GetNamespacesRepositoriesImagesSummary
@ -366,29 +323,28 @@ paths:
- name: active_from
in: query
required: false
description: >
description: |
Sets the time from which an image must have been pushed or pulled to
be counted as active.
Defaults to 1 month before the current time.
schema:
type: string
responses:
"200":
200:
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesSummaryResp\
onse"
"401":
$ref:
"#/components/schemas/GetNamespaceRepositoryImagesSummaryResponse"
401:
description: Unauthorized - user does not have read access to the namespace
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/repositories/{repository}/images":
/v2/namespaces/{namespace}/repositories/{repository}/images:
get:
tags:
- images
@ -422,8 +378,8 @@ paths:
required: false
description: |
Filters to only show images with:
* `true`: at least 1 current tag.
* `false`: no current tags.
- `true`: at least 1 current tag.
- `false`: no current tags.
schema:
type: boolean
- name: ordering
@ -443,11 +399,10 @@ paths:
- name: active_from
in: query
required: false
description: >
description: |
Sets the time from which an image must have been pushed or pulled to
be counted as active.
Defaults to 1 month before the current time.
schema:
type: string
@ -464,25 +419,25 @@ paths:
schema:
type: integer
responses:
"200":
200:
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesResponse"
"401":
401:
description: Unauthorized - user does not have read access to the namespace.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"403":
403:
description: Forbidden - this API is only available to users on Pro or Team plans.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags":
/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags:
get:
tags:
- images
@ -521,43 +476,39 @@ paths:
schema:
type: integer
responses:
"200":
200:
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesTagsResponse"
"401":
401:
description: Unauthorized - user does not have read access to the namespace
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"403":
403:
description: Forbidden - this API is only available to users on Pro or Team plans
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/delete-images":
/v2/namespaces/{namespace}/delete-images:
post:
tags:
- images
summary: Delete images
operationId: PostNamespacesDeleteImages
description: >
Deletes one or more images within a namespace. This is currently limited
to a single repostiory.
description: |
Deletes one or more images within a namespace. This is currently limited to a single
repository.
If you attempt to delete images that are marked as active or are currently tagged, the deletion does not happen and it displays the warnings.
To continue with the deletion, you must ignore these warnings by putting them in the `ignore_warnings` property.
Deleting a currently tagged image deletes the tag from the repository.
You cannot ignore errors. It is not possible to directly delete children of multi-arch images.
parameters:
- name: namespace
@ -574,32 +525,31 @@ paths:
description: Delete request.
required: true
responses:
"200":
200:
description: Deletion completed
content:
application/json:
schema:
$ref: "#/components/schemas/PostNamespacesDeleteImagesResponseSucce\
ss"
"400":
$ref: "#/components/schemas/PostNamespacesDeleteImagesResponseSuccess"
400:
description: Deletion not possible
content:
application/json:
schema:
$ref: "#/components/schemas/PostNamespacesDeleteImagesResponseError"
"403":
403:
description: Forbidden - this API is only available to users on Pro or Team plans
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/v2/auditlogs/{account}":
/v2/auditlogs/{account}:
get:
summary: Returns list of audit log events.
description: Get audit log events for a given namespace.
operationId: AuditLogs_GetAuditLogs
responses:
"200":
200:
description: A successful response.
content:
application/json:
@ -617,9 +567,10 @@ paths:
digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa
tag: latest
timestamp: 2021-02-19T01:34:35Z
action_description: pushed the tag latest with the digest
action_description:
pushed the tag latest with the digest
sha256:c1ae9c435032a to the repository docker/example
"429":
429:
description: ""
content:
application/json:
@ -629,7 +580,7 @@ paths:
value:
detail: Rate limit exceeded
error: false
"500":
500:
description: ""
content:
application/json:
@ -648,14 +599,16 @@ paths:
schema:
type: string
- name: action
description: action name one of ["repo.tag.push", ...]. Optional parameter to
description:
action name one of ["repo.tag.push", ...]. Optional parameter to
filter specific audit log actions.
in: query
required: false
schema:
type: string
- name: name
description: name. Optional parameter to filter audit log events to a specific
description:
name. Optional parameter to filter audit log events to a specific
name. For repository events, this is the name of the repository. For
organization events, this is the name of the organization. For team
member events, this is the username of the team member.
@ -664,7 +617,8 @@ paths:
schema:
type: string
- name: actor
description: actor name. Optional parameter to filter audit log events to the
description:
actor name. Optional parameter to filter audit log events to the
specific user who triggered the event.
in: query
required: false
@ -702,14 +656,15 @@ paths:
default: 25
tags:
- audit-logs
"/v2/auditlogs/{account}/actions":
/v2/auditlogs/{account}/actions:
get:
summary: Returns list of audit log actions.
description: Get audit log actions for a namespace to be used as a filter for
description:
Get audit log actions for a namespace to be used as a filter for
querying audit events.
operationId: AuditLogs_GetAuditActions
responses:
"200":
200:
description: A successful response.
content:
application/json:
@ -761,7 +716,7 @@ paths:
description: contains image tag delete events
label: Tag Deleted
label: Repository
"429":
429:
description: ""
content:
application/json:
@ -771,7 +726,7 @@ paths:
value:
detail: Rate limit exceeded
error: false
"500":
500:
description: ""
content:
application/json:
@ -791,7 +746,7 @@ paths:
type: string
tags:
- audit-logs
"/v2/orgs/{name}/settings":
/v2/orgs/{name}/settings:
parameters:
- in: path
name: name
@ -806,30 +761,27 @@ paths:
tags:
- org-settings
responses:
"200":
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/orgSettings"
"401":
401:
$ref: "#/components/responses/Unauthorized"
"403":
403:
$ref: "#/components/responses/Forbidden"
"404":
404:
$ref: "#/components/responses/NotFound"
put:
summary: Update organization settings
description: >
description: |
Updates an organization's settings. Some settings are only used when the
organization is on a business plan.
***Only users in the "owners" group of the organization can use this endpoint.***
The following settings are only used on a business plan:
- `restricted_images`
tags:
- org-settings
@ -850,19 +802,19 @@ paths:
- allow_verified_publishers
required: true
responses:
"200":
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/orgSettings"
"401":
401:
$ref: "#/components/responses/Unauthorized"
"403":
403:
$ref: "#/components/responses/Forbidden"
"404":
404:
$ref: "#/components/responses/NotFound"
"/v2/repositories/{namespace}/{repository}/":
/v2/repositories/{namespace}/{repository}/:
parameters:
- name: namespace
in: path
@ -880,17 +832,13 @@ paths:
tags:
- repositories
summary: Update repository configuration
description: >
description: |
Update the configuration of a repository:
- description: the summary of a repository
- full description: the readme displayed on repository's page, markdown accepted
- visibility: is the repository public or private
Authentication is required.
operationId: PatchRepositoryDescription
requestBody:
@ -899,14 +847,15 @@ paths:
schema:
$ref: "#/components/schemas/update_repository"
responses:
"200":
200:
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/repository"
"403":
description: Forbidden - access to the resource is forbidden, you don't have
403:
description:
Forbidden - access to the resource is forbidden, you don't have
needed permission to perform this action.
content:
application/json:
@ -916,8 +865,8 @@ paths:
response:
value:
detail: You do not have permission to perform this action.
"404":
description: Repository not found or unable to access the ressource
404:
description: Repository not found or unable to access the resource
content:
application/json:
schema:
@ -967,7 +916,8 @@ components:
type: string
example: myusername
password:
description: The password or personal access token (PAT) of the Docker Hub
description:
The password or personal access token (PAT) of the Docker Hub
account to authenticate with.
type: string
example: hunter2
@ -976,7 +926,7 @@ components:
type: object
properties:
token:
description: >
description: |
Created authentication token.
This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.
@ -995,7 +945,8 @@ components:
example: Incorrect authentication credentials
nullable: false
login_2fa_token:
description: Short time lived token to be used on `/v2/users/2fa-login` to
description:
Short time lived token to be used on `/v2/users/2fa-login` to
complete the authentication. This field is present only if 2FA is
enabled.
type: string
@ -1013,7 +964,8 @@ components:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
code:
description: The Time-based One-Time Password of the Docker Hub account to
description:
The Time-based One-Time Password of the Docker Hub account to
authenticate with.
type: string
example: 123456
@ -1066,7 +1018,8 @@ components:
type: object
properties:
active_from:
description: Time from which an image must have been pushed or pulled to be
description:
Time from which an image must have been pushed or pulled to be
counted as active.
type: string
example: 2021-01-25T14:25:37.076343059Z
@ -1094,13 +1047,15 @@ components:
type: integer
example: 100
next:
description: Link to the next page with the same query parameters if there are
description:
Link to the next page with the same query parameters if there are
more images.
type: string
example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20
nullable: true
previous:
description: Link to the previous page with the same query parameters if not on
description:
Link to the previous page with the same query parameters if not on
first page.
type: string
example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20
@ -1134,10 +1089,9 @@ components:
type: string
example: latest
is_current:
description: >
description: |
`true` if the tag currently points to this image.
`false` if it has been overwritten to point at a different image.
type: boolean
example: true
@ -1147,13 +1101,15 @@ components:
example: 2021-02-24T22:05:27.526308Z
nullable: true
last_pulled:
description: Time when this image was last pulled. Note this is updated at
description:
Time when this image was last pulled. Note this is updated at
most once per hour.
type: string
example: 2021-02-24T23:16:10.200008Z
nullable: true
status:
description: The status of the image based on its last activity against the
description:
The status of the image based on its last activity against the
`active_from` time.
type: string
enum:
@ -1189,10 +1145,9 @@ components:
type: string
example: latest
is_current:
description: >
description: |
`true` if the tag currently points to this image.
`false` if it has been overwritten to point at a different image.
type: boolean
example: true
@ -1201,16 +1156,16 @@ components:
type: object
properties:
dry_run:
description: If `true` then will check and return errors and unignored warnings
description:
If `true` then will check and return errors and unignored warnings
for the deletion request but will not delete any images.
type: boolean
example: false
active_from:
description: >
description: |
Sets the time from which an image must have been pushed or pulled to
be counted as active.
Defaults to 1 month before the current time.
type: string
example: 2020-12-01T12:00:00Z
@ -1232,19 +1187,15 @@ components:
type: string
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
ignore_warnings:
description: >
Warnings to ignore. If a warning is not ignored then no deletions
will happen and the warning is returned in the response.
description: |
Warnings to ignore. If a warning is not ignored then no deletions will happen and the
warning is returned in the response.
These warnings include:
* is_active: warning when attempting to delete an image that is marked as active.
* current_tag: warning when attempting to delete an image that has one or more current tags in the repository.
- is_active: warning when attempting to delete an image that is marked as active.
- current_tag: warning when attempting to delete an image that has one or more current
tags in the repository.
Warnings can be copied from the response to the request.
type: array
@ -1326,14 +1277,16 @@ components:
type: object
properties:
errors:
description: Errors from validating delete request. These cannot be
description:
Errors from validating delete request. These cannot be
ignored.
type: array
items:
type: object
properties:
repository:
description: Name of the repository of the image that caused
description:
Name of the repository of the image that caused
the error.
type: string
example: myrepo
@ -1350,18 +1303,15 @@ components:
- child_manifest
example: not_found
warnings:
description: >
description: |
Warnings that can be ignored.
These warnings include:
* is_active: warning when attempting to delete an image that is marked as active.
* current_tag: warning when attempting to delete an image that has one or more current tags in the repository.
- is_active: warning when attempting to delete an image that is marked as
active.
- current_tag: warning when attempting to delete an image that has one or
more current tags in the repository.
Warnings can be copied from the response to the request.
type: array
@ -1369,7 +1319,8 @@ components:
type: object
properties:
repository:
description: Name of the repository of the image that caused
description:
Name of the repository of the image that caused
the warning.
type: string
example: myrepo
@ -1542,8 +1493,8 @@ components:
example: My read only token
scopes:
type: array
description: 'Valid scopes: "repo:admin", "repo:write", "repo:read",
"repo:public_read"'
description: |
Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read"
example:
- repo:read
items:
@ -1611,32 +1562,25 @@ components:
properties:
description:
type: string
description: The description of a repository, as displayed below the repository
description:
The description of a repository, as displayed below the repository
name.
example: Hello World! (an example of minimal Dockerization)
full_description:
type: string
description: The full description displayed on the repository page. Markdown
description:
The full description displayed on the repository page. Markdown
accepted.
example: >
example: |
# Quick reference
* Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
- Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
# Example output
```
$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.
```
repository:
type: object
@ -1663,24 +1607,15 @@ components:
full_description:
type: string
description: Description (readme) of the repository, in Markdown
example: >-
example: |
# Quick reference
* Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
- Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
# Example output
```
$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.
```