mirror of https://github.com/docker/docs.git
529 lines
18 KiB
YAML
529 lines
18 KiB
YAML
swagger: '2.0'
|
|
schemes:
|
|
- https
|
|
produces:
|
|
- application/json
|
|
basePath: /v2
|
|
info:
|
|
title: Docker HUB API
|
|
version: '2.0'
|
|
x-logo:
|
|
url: https://docs.docker.com/images/logo-docker-main.png
|
|
description: |
|
|
TBD
|
|
tags:
|
|
# Primary objects
|
|
- name: Authentication
|
|
x-displayName: Authentication
|
|
description: Authentication with the API
|
|
- name: Images
|
|
x-displayName: Images
|
|
description: Get and manage images within a repository
|
|
|
|
definitions:
|
|
UsersLoginRequest:
|
|
description: User login details
|
|
type: object
|
|
properties:
|
|
username:
|
|
description: The username of the Docker Hub account to authenticate with
|
|
type: string
|
|
required: true
|
|
example: myusername
|
|
password:
|
|
description: The password of the Docker Hub account to authenticate with
|
|
type: string
|
|
required: true
|
|
example: hunter2
|
|
PostUsersLoginSuccessResponse:
|
|
description: successful user login response
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
Created authentication token.
|
|
This token can be used in the HTTP Authentication header as a JWT to authenticate with the Docker Hub APIs
|
|
type: string
|
|
x-nullable: false
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
|
PostUsersLoginErrorResponse:
|
|
description: failed user login response
|
|
type: object
|
|
properties:
|
|
details:
|
|
description: Description of the error
|
|
type: string
|
|
x-nullable: false
|
|
example: Incorrect authentication credentials
|
|
ErrorInfo:
|
|
description: Context information for an error used for diagnostics
|
|
type: object
|
|
properties:
|
|
api_call_docker_id:
|
|
description: ID of docker user
|
|
type: string
|
|
api_call_name:
|
|
description: Name of the API operation called
|
|
type: string
|
|
api_call_start:
|
|
description: Date/time of call start
|
|
type: string
|
|
api_call_txnid:
|
|
description: Unique ID for this call
|
|
type: string
|
|
ErrorResponse:
|
|
description: Represents an error.
|
|
type: object
|
|
properties:
|
|
txnid:
|
|
description: Unique ID for this call
|
|
type: string
|
|
message:
|
|
description: The error message
|
|
type: string
|
|
errinfo:
|
|
$ref: '#/definitions/ErrorInfo'
|
|
GetNamespaceRepositoryImagesSummaryResponse:
|
|
description: Summary information for images in a repository
|
|
type: object
|
|
properties:
|
|
active_from:
|
|
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'
|
|
statistics:
|
|
type: object
|
|
properties:
|
|
total:
|
|
description: Number of images in this repository
|
|
type: integer
|
|
example: 3
|
|
active:
|
|
description: Number of images counted as active in this repository
|
|
type: integer
|
|
example: 2
|
|
inactive:
|
|
description: Number of images counted as inactive in this repository
|
|
type: integer
|
|
example: 1
|
|
GetNamespaceRepositoryImagesResponse:
|
|
description: Paginated list of images in a repository
|
|
type: object
|
|
properties:
|
|
count:
|
|
description: Total count of images in the repository
|
|
type: integer
|
|
example: 100
|
|
next:
|
|
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
|
|
x-nullable: true
|
|
previous:
|
|
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
|
|
x-nullable: true
|
|
results:
|
|
type: array
|
|
description: Image details
|
|
items:
|
|
type: object
|
|
properties:
|
|
namespace:
|
|
description: The repository namespace
|
|
type: string
|
|
example: mynamespace
|
|
repository:
|
|
description: The repository name
|
|
type: string
|
|
example: myrepo
|
|
digest:
|
|
description: The image's digest
|
|
type: string
|
|
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
|
|
tags:
|
|
description: The current and historical tags for this image
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
tag:
|
|
description: The tag
|
|
type: string
|
|
example: latest
|
|
is_current:
|
|
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
|
|
last_pushed:
|
|
description: Time when this image was last pushed
|
|
type: string
|
|
x-nullable: true
|
|
example: '2021-02-24T22:05:27.526308Z'
|
|
last_pulled:
|
|
description: Time when this image was last pulled. Note this is updated at most once per hour
|
|
type: string
|
|
x-nullable: true
|
|
example: '2021-02-24T23:16:10.200008Z'
|
|
status:
|
|
description: The status of the image based on it's last activity against the active_from time
|
|
type: string
|
|
enum: [active, inactive]
|
|
example: active
|
|
PostNamespacesDeleteImagesRequest:
|
|
description: Delete images request
|
|
type: object
|
|
properties:
|
|
dry_run:
|
|
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: |
|
|
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'
|
|
manifests:
|
|
description: Image manifests to delete
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
repository:
|
|
description: Name of repository to delete the image from
|
|
required: true
|
|
type: string
|
|
example: myrepo
|
|
digest:
|
|
description: Digest of the image to delete
|
|
required: true
|
|
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
|
|
|
|
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
|
|
|
|
Warnings can be copied from the response to the request
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
repository:
|
|
description: Name of the repository of the image to ignore the warning for
|
|
required: true
|
|
type: string
|
|
example: myrepo
|
|
digest:
|
|
description: Digest of the image to ignore the warning for
|
|
required: true
|
|
type: string
|
|
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
|
|
warning:
|
|
description: Warning to ignore
|
|
required: true
|
|
type: string
|
|
enum: [is_active, current_tag]
|
|
example: current_tag
|
|
tags:
|
|
description: Current tags to ignore
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: latest
|
|
PostNamespacesDeleteImagesResponseSuccess:
|
|
description: Successful delete images response
|
|
type: object
|
|
properties:
|
|
dry_run:
|
|
description: Whether the request was a dry run or not
|
|
type: boolean
|
|
example: false
|
|
metrics:
|
|
type: object
|
|
properties:
|
|
manifest_deletes:
|
|
description: Number of manifests deleted
|
|
type: integer
|
|
example: 3
|
|
manifest_errors:
|
|
description: Number of manifests that failed to delete
|
|
type: integer
|
|
example: 0
|
|
tag_deletes:
|
|
description: Number of tags deleted
|
|
type: integer
|
|
example: 1
|
|
tag_errors:
|
|
description: Number of tags that failed to delete
|
|
type: integer
|
|
example: 0
|
|
PostNamespacesDeleteImagesResponseError:
|
|
description: Deletion not possible
|
|
type: object
|
|
properties:
|
|
txnid:
|
|
description: Unique ID for this call
|
|
type: string
|
|
message:
|
|
description: The error message
|
|
type: string
|
|
errinfo:
|
|
allOf:
|
|
- $ref: '#/definitions/ErrorInfo'
|
|
- type: object
|
|
properties:
|
|
type:
|
|
description: Type of error
|
|
type: string
|
|
example: validation
|
|
details:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
description: Errors from validating delete request. These cannot be ignored
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
repository:
|
|
description: Name of repository of the image that caused the error
|
|
type: string
|
|
example: myrepo
|
|
digest:
|
|
description: Digest of the image that caused the error
|
|
type: string
|
|
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
|
|
error:
|
|
description: Error type
|
|
type: string
|
|
enum: [not_found, unauthorized, child_manifest]
|
|
example: not_found
|
|
warnings:
|
|
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
|
|
|
|
Warnings can be copied from the response to the request
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
repository:
|
|
description: Name of the repository of the image that caused the warning
|
|
type: string
|
|
example: myrepo
|
|
digest:
|
|
description: Digest of the image that caused the warning
|
|
type: string
|
|
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
|
|
warning:
|
|
description: Warning type
|
|
type: string
|
|
enum: [is_active, current_tag]
|
|
example: current_tag
|
|
tags:
|
|
description: Current tags if warning is `current_tag`
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: latest
|
|
paths:
|
|
/v2/users/login:
|
|
post:
|
|
tags: [Authentication]
|
|
summary: Create authentication token
|
|
operationId: PostUsersLogin
|
|
description: |
|
|
Creates an authentication token that can be used to authenticate with the Docker Hub APIs.
|
|
|
|
The returned token is used in the HTTP Authentication header like `Authentication: JWT {TOKEN}`
|
|
|
|
Most Docker Hub APIs require this token either to consume or to get detailed information (e.g. listing images of the private repository).
|
|
consume:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: body
|
|
in: body
|
|
description: Login details
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/UsersLoginRequest'
|
|
responses:
|
|
200:
|
|
description: Authentication successful
|
|
schema:
|
|
$ref: '#/definitions/PostUsersLoginSuccessResponse'
|
|
401:
|
|
description: Authentication failed
|
|
schema:
|
|
$ref: '#/definitions/PostUsersLoginErrorResponse'
|
|
/v2/namespaces/{namespace}/repositories/{repository}/images-summary:
|
|
get:
|
|
tags: [Images]
|
|
summary: Get summary of repository's images
|
|
description: |
|
|
Gets the number of images in a repository and the number of images counted as active and inactive
|
|
operationId: GetNamespacesRepositorieImagesSummary
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: namespace
|
|
in: path
|
|
required: true
|
|
description: Namespace of repository
|
|
type: string
|
|
- name: repository
|
|
in: path
|
|
required: true
|
|
description: Name of repository
|
|
type: string
|
|
- name: active_from
|
|
in: query
|
|
required: false
|
|
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'
|
|
responses:
|
|
200:
|
|
description: Success
|
|
schema:
|
|
$ref: '#/definitions/GetNamespaceRepositoryImagesSummaryResponse'
|
|
401:
|
|
description: Unauthorized - user does not have read access to the namespace
|
|
schema:
|
|
$ref: '#/definitions/ErrorResponse'
|
|
/v2/namespaces/{namespace}/repositories/{repository}/images:
|
|
get:
|
|
tags: [Images]
|
|
summary: Get details of repository's images
|
|
description: |
|
|
Limited to users on Pro and Team plans
|
|
|
|
Gets details on the images in a repository
|
|
operationId: GetNamespacesRepositoriesImages
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: namespace
|
|
in: path
|
|
required: true
|
|
description: Namespace of repository
|
|
type: string
|
|
- name: repository
|
|
in: path
|
|
required: true
|
|
description: Name of repository
|
|
type: string
|
|
- name: status
|
|
in: query
|
|
required: false
|
|
description: Filters to only show images of this status
|
|
type: string
|
|
enum: [active, inactive]
|
|
- name: ordering
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Orders the results by this property
|
|
|
|
Prefixing with `-` sorts by descending order
|
|
type: string
|
|
enum: [last_activity, -last_activity, digest, -digest]
|
|
- name: active_from
|
|
in: query
|
|
required: false
|
|
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'
|
|
- name: page
|
|
in: query
|
|
required: false
|
|
description: Page number to get. Defaults to 1
|
|
type: integer
|
|
- name: page_size
|
|
in: query
|
|
required: false
|
|
description: Number of images to get per page. Defaults to 10. Max of 100.
|
|
type: integer
|
|
responses:
|
|
200:
|
|
description: Success
|
|
schema:
|
|
$ref: '#/definitions/GetNamespaceRepositoryImagesResponse'
|
|
401:
|
|
description: Unauthorized - user does not have read access to the namespace
|
|
schema:
|
|
$ref: '#/definitions/ErrorResponse'
|
|
403:
|
|
description: Forbidden - this API is only available to users on Pro or Team plans
|
|
schema:
|
|
$ref: '#/definitions/ErrorResponse'
|
|
/v2/namespaces/{namespace}/delete-images:
|
|
post:
|
|
tags: [Images]
|
|
summary: Delete images
|
|
operationId: PostNamespacesDeleteImages
|
|
description: |
|
|
Deletes one or more images withing a namespace (note: currently limited to a single repostiory).
|
|
|
|
If you attempt to delete images that are marked as active or are currently tagged then the deletions will not happen and these warnings will be returned.
|
|
To continue with the deletion you must ignore these warnings by putting them in the `ignore_warnings` property.
|
|
|
|
Deleting a currently tagged image will delete the tag from the repository.
|
|
|
|
Errors cannot be ignored. Children of multi-arch images cannot be directly deleted.
|
|
consume:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: namespace
|
|
in: path
|
|
required: true
|
|
description: Namespace of repository
|
|
type: string
|
|
- name: body
|
|
in: body
|
|
description: Login details
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/PostNamespacesDeleteImagesRequest'
|
|
responses:
|
|
200:
|
|
description: Deletion completed
|
|
schema:
|
|
$ref: '#/definitions/PostNamespacesDeleteImagesResponseSuccess'
|
|
400:
|
|
description: Deletion not possible
|
|
schema:
|
|
$ref: '#/definitions/PostNamespacesDeleteImagesResponseError'
|
|
403:
|
|
description: Forbidden - this API is only available to users on Pro or Team plans
|
|
schema:
|
|
$ref: '#/definitions/ErrorResponse'
|