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

Add access tokens API documentation (#13174) 

* feat(hub-api): Add access tokens API documentation.

Also added improvements including
- improvements to slugs (ids) using standard swagger naming conventions
- rate limiting section
- minor verbiage changes to existing docs for clarity

* chore(hub-api): Update PAT description on scopes

* ref(hub-api): Remove periods

* feat(hub-api): Add suggested note on limits

* ref(hub-api): Improve styling for hub-api docs

* chore(hub-api): Update verbiage

* Update docker-hub/api/latest.yaml

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>

* chore(hub-api): Update access token verbiage

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>
This commit is contained in:
Josh Newman 2021-07-20 11:26:43 -06:00 committed by GitHub
parent 7f3af332cc
commit c5b1a6ad00
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 343 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_layouts/hub-api.html
View File

@ -16,7 +16,7 @@
<link rel="canonical" href="https://docs.docker.com/docker-hub/api/latest/" /> <link rel="canonical" href="https://docs.docker.com/docker-hub/api/latest/" />
</head> </head>
<body> <body>
<redoc spec-url="/docker-hub/api/{{ page.name | replace: '.md'}}.yaml" hide-hostname="false" suppress-warnings="false"></redoc> <redoc spec-url="/docker-hub/api/{{ page.name | replace: '.md'}}.yaml" hide-hostname="false" suppress-warnings="false" class="hub-api"></redoc>
<script src="/js/redoc.min.js"></script> <script src="/js/redoc.min.js"></script>
</body> </body>
</html> </html>

17
css/api-reference.scss
View File

@ -15,6 +15,7 @@ body {
margin: 0; margin: 0;
padding: 0; padding: 0;
} }
api-logo { api-logo {
background-color: $bg-header; background-color: $bg-header;
height: 60px; height: 60px;
@ -30,22 +31,38 @@ redoc {
h1 { h1 {
font-size: 32px !important; font-size: 32px !important;
} }
h1,h2,h3,h4,h5,h6 { h1,h2,h3,h4,h5,h6 {
font-family: $headings !important; font-family: $headings !important;
color: inherit !important; color: inherit !important;
} }
p, a, .menu-item-title { p, a, .menu-item-title {
font-family: $font !important; font-family: $font !important;
} }
a, .menu-item-title { a, .menu-item-title {
color: $primary-links !important; color: $primary-links !important;
} }
.menu-item-title { .menu-item-title {
text-transform: none; text-transform: none;
} }
// Disable request-type badges, see https://github.com/Rebilly/ReDoc/issues/61 // Disable request-type badges, see https://github.com/Rebilly/ReDoc/issues/61
.operation-type { .operation-type {
display: none !important; display: none !important;
} }
} }
// Hub API docs uses tag groups.
redoc.hub-api {
// tag group name
.menu-item-depth-0 > .menu-item-header:first-child .menu-item-title {
color: $body-text !important;
}
.menu-item-for-operation .menu-item-header .menu-item-title {
padding-left: 1em !important;
}
}

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

@ -1,12 +1,13 @@
swagger: '2.0' swagger: '2.0'
host: hub.docker.com
basePath: '/'
schemes: schemes:
- https - https
host: hub.docker.com
basePath: "/"
produces:
- application/json
consumes: consumes:
- application/json - application/json
produces:
- application/json
info: info:
title: Docker HUB API title: Docker HUB API
version: 'beta' version: 'beta'
@ -18,37 +19,93 @@ info:
In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental),
Docker provides an API that allows you to interact with Docker Hub. Docker provides an API that allows you to interact with Docker Hub.
Browse through the Docker Hub API documentation to explore the supported endpoints. Browse through the Docker Hub API documentation to explore the supported endpoints.
tags: tags:
# Primary objects - name: rate-limiting
- name: Authentication x-displayName: Rate Limiting
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-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.
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
download, or pull rate limiting. To learn more about Docker Hub pull rate
limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/).*
- name: authentication
x-displayName: Authentication x-displayName: Authentication
description: | description: |
Most Docker Hub API endpoints require you to authenticate using your Docker credentials. 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). 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: Images - name: access-tokens
x-displayName: Advanced image management 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.
### 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*
`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.***
- name: images
x-displayName: Advanced Image Management
description: | description: |
The Advanced Image Management API endpoints allow you to manage Docker images across all repositories. 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/). For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/).
- name: Audit Logs - name: audit-logs
x-displayName: Audit Logs x-displayName: Audit Logs
description: | description: |
The Audit Logs API endpoints allow you to query audit log events across a namespace. 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/) For more information, see [Audit Log](https://docs.docker.com/docker-hub/audit-log/)
x-tagGroups:
- name: General
tags:
- rate-limiting
- name: API
tags:
- authentication
- access-tokens
- images
- audit-logs
definitions: definitions:
UsersLoginRequest: UsersLoginRequest:
description: User login details description: User login details
type: object type: object
required: [username, password] required: [username, password]
properties: properties:
username: username:
description: The username of the Docker Hub account to authenticate with. description: The username of the Docker Hub account to authenticate with.
type: string type: string
example: myusername example: myusername
password: password:
description: The password of the Docker Hub account to authenticate with. description: The password or personal access token (PAT) of the Docker Hub account to authenticate with.
type: string type: string
example: hunter2 example: hunter2
PostUsersLoginSuccessResponse: PostUsersLoginSuccessResponse:
@ -229,15 +286,15 @@ definitions:
description: Delete images request. description: Delete images request.
type: object type: object
properties: properties:
dry_run: dry_run:
description: If `true` then will check and return errors and unignored warnings for the deletion request but will not delete any images. description: If `true` then will check and return errors and unignored warnings for the deletion request but will not delete any images.
type: boolean type: boolean
example: false example: false
active_from: active_from:
description: | description: |
Sets the time from which an image must have been pushed or pulled to be counted as active. 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. Defaults to 1 month before the current time.
type: string type: string
example: '2020-12-01T12:00:00Z' example: '2020-12-01T12:00:00Z'
manifests: manifests:
@ -262,7 +319,7 @@ definitions:
These warnings include: These warnings include:
* is_active: warning when attempting to delete an image that is marked as active. * 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. * 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. Warnings can be copied from the response to the request.
@ -349,7 +406,7 @@ definitions:
description: Name of the repository of the image that caused the error. description: Name of the repository of the image that caused the error.
type: string type: string
example: myrepo example: myrepo
digest: digest:
description: Digest of the image that caused the error. description: Digest of the image that caused the error.
type: string type: string
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
@ -365,7 +422,7 @@ definitions:
These warnings include: These warnings include:
* is_active: warning when attempting to delete an image that is marked as active. * 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. * 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. Warnings can be copied from the response to the request.
@ -475,16 +532,130 @@ definitions:
action_description: action_description:
type: string type: string
description: Audit log event. description: Audit log event.
ValueError:
type: object
description: Used to error if input validation fails.
properties:
fields:
type: object
items:
type: string
text:
type: string
Error:
type: object
properties:
detail:
type: string
message:
type: string
# Access Tokens
accessToken:
type: object
properties:
uuid:
type: string
example: b30bbf97-506c-4ecd-aabc-842f3cb484fb
client_id:
type: string
example: HUB
creator_ip:
type: string
example: 127.0.0.1
creator_ua:
type: string
example: some user agent
created_at:
type: string
example: 2021-07-20T12:00:00.000000Z
last_used:
type: string
x-nullable: true
example: null
generated_by:
type: string
example: manual
is_active:
type: boolean
example: true
token:
type: string
example: a7a5ef25-8889-43a0-8cc7-f2a94268e861
token_label:
type: string
example: My read only token
scopes:
type: array
example: ['repo:read']
items:
type: string
createAccessTokenRequest:
type: object
required:
- token_label
- scopes
properties:
token_label:
type: string
description: Friendly name for you to identify the token.
example: My read only token
scopes:
type: array
description: 'Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read"'
example: ['repo:read']
items:
type: string
createAccessTokensResponse:
type: object
$ref: '#/definitions/accessToken'
getAccessTokensResponse:
type: object
properties:
count:
type: number
example: 1
next:
type: string
example: null
previous:
type: string
example: null
active_count:
type: number
example: 1
results:
type: array
items:
allOf:
- $ref: '#/definitions/accessToken'
- type: object
properties:
token:
type: string
example: ''
patchAccessTokenRequest:
type: object
properties:
token_label:
type: string
example: My read only token
is_active:
type: boolean
example: false
patchAccessTokenResponse:
type: object
$ref: '#/definitions/accessToken'
paths: paths:
/v2/users/login: /v2/users/login:
post: post:
tags: [Authentication] tags: [authentication]
summary: Create authentication token summary: Create an authentication token
operationId: PostUsersLogin operationId: PostUsersLogin
description: | description: |
Creates an authentication token that can be used to authenticate with the Docker Hub APIs. 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: JWT {TOKEN}`. 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. Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
parameters: parameters:
@ -503,9 +674,113 @@ paths:
description: Authentication failed description: Authentication failed
schema: schema:
$ref: '#/definitions/PostUsersLoginErrorResponse' $ref: '#/definitions/PostUsersLoginErrorResponse'
/v2/access-tokens:
post:
summary: Create a personal access token
description: Creates and returns a personal access token.
tags: [access-tokens]
parameters:
- in: body
name: body
required: true
schema:
$ref: '#/definitions/createAccessTokenRequest'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/createAccessTokensResponse'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
get:
summary: Get a list of personal access tokens
description: Returns a paginated list of personal access tokens.
tags: [access-tokens]
parameters:
- in: query
name: page
type: number
default: 1
- in: query
name: page_size
type: number
default: 10
responses:
'200':
description: OK
schema:
$ref: '#/definitions/getAccessTokensResponse'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
/v2/access-tokens/{uuid}:
patch:
summary: Update a personal access token
description: |
Updates a personal access token partially. You can either update the
token's label or enable/disable it.
tags: [access-tokens]
parameters:
- in: path
name: uuid
required: true
type: string
- in: body
name: request body
required: true
schema:
$ref: '#/definitions/patchAccessTokenRequest'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/patchAccessTokenResponse'
'400':
$ref: '#/responses/BadRequest'
'401':
$ref: '#/responses/Unauthorized'
get:
summary: Get a personal access token
description: Returns a personal access token by UUID.
tags: [access-tokens]
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/accessToken'
- type: object
properties:
token:
type: string
example: ''
'401':
$ref: '#/responses/Unauthorized'
'404':
$ref: '#/responses/NotFound'
delete:
summary: Delete a personal access token
description: |
Deletes a personal access token permanently. This cannot be undone.
tags: [access-tokens]
parameters:
- in: path
name: uuid
required: true
type: string
responses:
'204':
description: A successful response.
'401':
$ref: '#/responses/Unauthorized'
'404':
$ref: '#/responses/NotFound'
/v2/namespaces/{namespace}/repositories/{repository}/images-summary: /v2/namespaces/{namespace}/repositories/{repository}/images-summary:
get: get:
tags: [Images] tags: [images]
summary: Get summary of repository's 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. Gets the number of images in a repository and the number of images counted as active and inactive.
@ -526,7 +801,7 @@ paths:
- name: active_from - name: active_from
in: query in: query
required: false required: false
description: | description: |
Sets the time from which an image must have been pushed or pulled to be counted as active. 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. Defaults to 1 month before the current time.
@ -534,7 +809,7 @@ paths:
responses: responses:
200: 200:
description: Success description: Success
schema: schema:
$ref: '#/definitions/GetNamespaceRepositoryImagesSummaryResponse' $ref: '#/definitions/GetNamespaceRepositoryImagesSummaryResponse'
401: 401:
description: Unauthorized - user does not have read access to the namespace description: Unauthorized - user does not have read access to the namespace
@ -542,7 +817,7 @@ paths:
$ref: '#/definitions/ErrorResponse' $ref: '#/definitions/ErrorResponse'
/v2/namespaces/{namespace}/repositories/{repository}/images: /v2/namespaces/{namespace}/repositories/{repository}/images:
get: get:
tags: [Images] tags: [images]
summary: Get details of repository's images summary: Get details of repository's images
description: Gets details on the images in a repository. description: Gets details on the images in a repository.
operationId: GetNamespacesRepositoriesImages operationId: GetNamespacesRepositoriesImages
@ -569,7 +844,7 @@ paths:
in: query in: query
required: false required: false
type: boolean type: boolean
description: | description: |
Filters to only show images with: Filters to only show images with:
* `true`: at least 1 current tag. * `true`: at least 1 current tag.
* `false`: no current tags. * `false`: no current tags.
@ -585,7 +860,7 @@ paths:
- name: active_from - name: active_from
in: query in: query
required: false required: false
description: | description: |
Sets the time from which an image must have been pushed or pulled to be counted as active. 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. Defaults to 1 month before the current time.
@ -603,7 +878,7 @@ paths:
responses: responses:
200: 200:
description: Success description: Success
schema: schema:
$ref: '#/definitions/GetNamespaceRepositoryImagesResponse' $ref: '#/definitions/GetNamespaceRepositoryImagesResponse'
401: 401:
description: Unauthorized - user does not have read access to the namespace. description: Unauthorized - user does not have read access to the namespace.
@ -615,7 +890,7 @@ paths:
$ref: '#/definitions/ErrorResponse' $ref: '#/definitions/ErrorResponse'
/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags: /v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags:
get: get:
tags: [Images] tags: [images]
summary: Get image's tags summary: Get image's tags
description: Gets current and historical tags for an image. description: Gets current and historical tags for an image.
operationId: GetNamespacesRepositoriesImagesTags operationId: GetNamespacesRepositoriesImagesTags
@ -650,7 +925,7 @@ paths:
responses: responses:
200: 200:
description: Success description: Success
schema: schema:
$ref: '#/definitions/GetNamespaceRepositoryImagesTagsResponse' $ref: '#/definitions/GetNamespaceRepositoryImagesTagsResponse'
401: 401:
description: Unauthorized - user does not have read access to the namespace description: Unauthorized - user does not have read access to the namespace
@ -662,7 +937,7 @@ paths:
$ref: '#/definitions/ErrorResponse' $ref: '#/definitions/ErrorResponse'
/v2/namespaces/{namespace}/delete-images: /v2/namespaces/{namespace}/delete-images:
post: post:
tags: [Images] tags: [images]
summary: Delete images summary: Delete images
operationId: PostNamespacesDeleteImages operationId: PostNamespacesDeleteImages
description: | description: |
@ -782,8 +1057,7 @@ paths:
type: integer type: integer
format: int32 format: int32
default: 25 default: 25
tags: tags: [audit-logs]
- "Audit Logs"
/v2/auditlogs/{account}/actions: /v2/auditlogs/{account}/actions:
get: get:
summary: Returns list of audit log actions. summary: Returns list of audit log actions.
@ -859,5 +1133,18 @@ paths:
in: path in: path
required: true required: true
type: string type: string
tags: tags: [audit-logs]
- "Audit Logs"
responses:
BadRequest:
description: Bad Request
schema:
$ref: '#/definitions/ValueError'
Unauthorized:
description: Unauthorized
schema:
$ref: '#/definitions/Error'
NotFound:
description: Not Found
schema:
$ref: '#/definitions/Error'