mirror of https://github.com/docker/docs.git
314 lines
10 KiB
YAML
314 lines
10 KiB
YAML
swagger: '2.0'
|
|
schemes:
|
|
- https
|
|
produces:
|
|
- application/json
|
|
basePath: /v2
|
|
info:
|
|
title: Docker HUB API
|
|
version: '2.0'
|
|
x-logo: 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
|
|
password:
|
|
description: The password of the Docker Hub account to authenticate with
|
|
type: string
|
|
required: true
|
|
UsersLoginSuccessResponse:
|
|
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
|
|
UsersLoginErrorResponse:
|
|
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'
|
|
NamespaceRepositoryImagesSummaryResponse:
|
|
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
|
|
NamespaceRepositoryImagesResponse:
|
|
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
|
|
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/UsersLoginSuccessResponse'
|
|
401:
|
|
description: Authentication failed
|
|
schema:
|
|
$ref: '#/definitions/UsersLoginErrorResponse'
|
|
/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: GetNamespaceRepositoryImagesSummary
|
|
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/NamespaceRepositoryImagesSummaryResponse'
|
|
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: GetNamespaceRepositoryImages
|
|
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/NamespaceRepositoryImagesResponse'
|
|
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'
|
|
|