mirror of https://github.com/docker/docs.git
Add initial image dashboard API docs
Signed-off-by: Nick Adcock <nick.adcock@docker.com>
This commit is contained in:
Nick Adcock
parent
96a4e1a430
commit
82ed0e463d
|
|
@ -21,6 +21,7 @@ exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html",
|
||||||
# Component versions -- address like site.docker_ce_version
|
# Component versions -- address like site.docker_ce_version
|
||||||
# You can't have - characters in these for non-YAML reasons
|
# You can't have - characters in these for non-YAML reasons
|
||||||
latest_engine_api_version: "1.41"
|
latest_engine_api_version: "1.41"
|
||||||
|
latest_hub_api_version: "2.0"
|
||||||
docker_ce_version: "20.10"
|
docker_ce_version: "20.10"
|
||||||
compose_version: "1.28.4"
|
compose_version: "1.28.4"
|
||||||
compose_file_v3: "3.9"
|
compose_file_v3: "3.9"
|
||||||
|
|
|
||||||
|
|
@ -1016,6 +1016,8 @@ reference:
|
||||||
title: v1.19 reference
|
title: v1.19 reference
|
||||||
- path: /engine/api/v1.18/
|
- path: /engine/api/v1.18/
|
||||||
title: v1.18 reference
|
title: v1.18 reference
|
||||||
|
- title: Docker Hub API
|
||||||
|
path: /docker-hub/api/latest/
|
||||||
- title: Registry API
|
- title: Registry API
|
||||||
path: /registry/spec/api/
|
path: /registry/spec/api/
|
||||||
- title: Dockerfile reference
|
- title: Dockerfile reference
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<title>Docker Hub API {{ page.name | replace: '.md' }} Reference</title>
|
||||||
|
<!-- needed for adaptive design -->
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||||
|
<meta name="description" content="Reference documentation and Swagger (OpenAPI) specification for the v{{ page.name | replace: '.md' }} version of the API served by Docker Hub." />
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<!-- favicon -->
|
||||||
|
<meta name="msapplication-TileImage" content="/favicons/docs@2x.ico" />
|
||||||
|
<meta property="og:image" content="/favicons/docs@2x.ico" />
|
||||||
|
<link rel="apple-touch-icon" type="image/x-icon" href="/favicons/docs@2x.ico" sizes="129x128" />
|
||||||
|
<link rel="icon" type="image/x-icon" href="/favicons/docs@2x.ico" sizes="129x128" />
|
||||||
|
<link rel="stylesheet" type="text/css" href="/css/api-reference.css" />
|
||||||
|
<!-- make the latest API version the canonical page as that's what we want users to be using mostly -->
|
||||||
|
<link rel="canonical" href="https://docs.docker.com/docker-hub/api/v{{ site.latest_hub_api_version }}/" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<redoc spec-url="/docker-hub/api/{{ page.name | replace: '.md'}}.yaml" hide-hostname="false" suppress-warnings="false"></redoc>
|
||||||
|
<script src="/js/redoc.min.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
@ -16,3 +16,8 @@ sedi () {
|
||||||
# in toc.yaml. This is brittle!
|
# in toc.yaml. This is brittle!
|
||||||
latest_engine_api_version="$(grep 'latest_engine_api_version:' ./_config.yml | grep -oh '"[0-9].*"$' | sed 's/"//g')"
|
latest_engine_api_version="$(grep 'latest_engine_api_version:' ./_config.yml | grep -oh '"[0-9].*"$' | sed 's/"//g')"
|
||||||
sedi "s/{{ site.latest_engine_api_version }}/${latest_engine_api_version}/g" ./_data/toc.yaml
|
sedi "s/{{ site.latest_engine_api_version }}/${latest_engine_api_version}/g" ./_data/toc.yaml
|
||||||
|
|
||||||
|
# Parse latest_hub_api_version variables from _config.yml to replace the value
|
||||||
|
# in toc.yaml. This is brittle!
|
||||||
|
latest_hub_api_version="$(grep 'latest_hub_api_version:' ./_config.yml | grep -oh '"[0-9].*"$' | sed 's/"//g')"
|
||||||
|
sedi "s/{{ site.latest_hub_api_version }}/${latest_hub_api_version}/g" ./_data/toc.yaml
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
---
|
||||||
|
---
|
||||||
|
<html>
|
||||||
|
<head><meta http-equiv="refresh" content="0;url=/docker-hub/api/v{{ site.latest_hub_api_version }}/" /></head>
|
||||||
|
<body><p>Redirecting to the latest version of the Docker Hub API reference.</body>
|
||||||
|
</html>
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
---
|
||||||
|
layout: hub-api
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,313 @@
|
||||||
|
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'
|
||||||
|
|
||||||
Loading…
Reference in New Issue