diff --git a/_config.yml b/_config.yml index deda4cb9cb..131e312efa 100644 --- a/_config.yml +++ b/_config.yml @@ -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" diff --git a/_data/toc.yaml b/_data/toc.yaml index d4f2dac18f..5cfc229d19 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -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 diff --git a/_layouts/hub-api.html b/_layouts/hub-api.html new file mode 100644 index 0000000000..64389ea53c --- /dev/null +++ b/_layouts/hub-api.html @@ -0,0 +1,22 @@ + + + + Docker Hub API {{ page.name | replace: '.md' }} Reference + + + + + + + + + + + + + + + + + + diff --git a/_scripts/update-api-toc.sh b/_scripts/update-api-toc.sh index 95608d4824..4c9c172763 100755 --- a/_scripts/update-api-toc.sh +++ b/_scripts/update-api-toc.sh @@ -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 diff --git a/docker-hub/api/latest/index.html b/docker-hub/api/latest/index.html new file mode 100644 index 0000000000..caef77b5ca --- /dev/null +++ b/docker-hub/api/latest/index.html @@ -0,0 +1,6 @@ +--- +--- + + +

Redirecting to the latest version of the Docker Hub API reference. + \ No newline at end of file diff --git a/docker-hub/api/v2.0.md b/docker-hub/api/v2.0.md new file mode 100644 index 0000000000..f2831098d1 --- /dev/null +++ b/docker-hub/api/v2.0.md @@ -0,0 +1,3 @@ +--- +layout: hub-api +--- diff --git a/docker-hub/api/v2.0.yaml b/docker-hub/api/v2.0.yaml new file mode 100644 index 0000000000..5a8cce209c --- /dev/null +++ b/docker-hub/api/v2.0.yaml @@ -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' +