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
|
||||
# You can't have - characters in these for non-YAML reasons
|
||||
latest_engine_api_version: "1.41"
|
||||
latest_hub_api_version: "2.0"
|
||||
docker_ce_version: "20.10"
|
||||
compose_version: "1.28.4"
|
||||
compose_file_v3: "3.9"
|
||||
|
|
|
|||
|
|
@ -1016,6 +1016,8 @@ reference:
|
|||
title: v1.19 reference
|
||||
- path: /engine/api/v1.18/
|
||||
title: v1.18 reference
|
||||
- title: Docker Hub API
|
||||
path: /docker-hub/api/latest/
|
||||
- title: Registry API
|
||||
path: /registry/spec/api/
|
||||
- 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!
|
||||
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
|
||||
|
||||
# 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