From d4747af3dc0cdc439402567583f73bfa9d65cefe Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 9 Aug 2016 12:03:35 +0200 Subject: [PATCH] docs: add missing "quiet" parameter for image/load and update response Progress reporting during image load was added in 415dd8688618ac2b3872c6a5b5af3afcef2c3e10, but the corresponding query-parameter was not documented in the API docs. This updates the API docs, and adds a response example both with quiet enabled and disabled. Signed-off-by: Sebastiaan van Stijn Upstream-commit: d13ed38471decb332e9a0872854a97730d548583 Component: engine --- .../docs/reference/api/docker_remote_api.md | 1 + .../reference/api/docker_remote_api_v1.23.md | 26 +++++++++++++++++++ .../reference/api/docker_remote_api_v1.24.md | 26 +++++++++++++++++++ .../reference/api/docker_remote_api_v1.25.md | 26 +++++++++++++++++++ 4 files changed, 79 insertions(+) diff --git a/components/engine/docs/reference/api/docker_remote_api.md b/components/engine/docs/reference/api/docker_remote_api.md index 986917548b..deafb1fe84 100644 --- a/components/engine/docs/reference/api/docker_remote_api.md +++ b/components/engine/docs/reference/api/docker_remote_api.md @@ -170,6 +170,7 @@ This section lists each version from latest to oldest. Each listing includes a * `POST /containers/create` with both `Hostname` and `Domainname` fields specified will result in the container's hostname being set to `Hostname`, rather than `Hostname.Domainname`. * `GET /volumes` now supports more filters, new added filters are `name` and `driver`. * `GET /containers/(id or name)/logs` now accepts a `details` query parameter to stream the extra attributes that were provided to the containers `LogOpts`, such as environment variables and labels, with the logs. +* `POST /images/load` now returns progress information as a JSON stream, and has a `quiet` query parameter to suppress progress details. ### v1.22 API changes diff --git a/components/engine/docs/reference/api/docker_remote_api_v1.23.md b/components/engine/docs/reference/api/docker_remote_api_v1.23.md index 0575dfce95..fcff64985a 100644 --- a/components/engine/docs/reference/api/docker_remote_api_v1.23.md +++ b/components/engine/docs/reference/api/docker_remote_api_v1.23.md @@ -2659,6 +2659,32 @@ See the [image tarball format](#image-tarball-format) for more details. **Example response**: HTTP/1.1 200 OK + Content-Type: application/json + Transfer-Encoding: chunked + + {"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[= ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[== ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[=== ] 98.3 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[===== ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"} + ... + {"stream":"Loaded image: busybox:latest\n"} + +**Example response**: + +If the "quiet" query parameter is set to `true` / `1` (`?quiet=1`), progress +details are suppressed, and only a confirmation message is returned as plain text +once the action completes. + + HTTP/1.1 200 OK + Content-Length: 29 + Content-Type: text/plain; charset=utf-8 + + Loaded image: busybox:latest + +**Query parameters**: + +- **quiet** – Boolean value, suppress progress details during load. Defaults + to `0` / `false` if omitted. **Status codes**: diff --git a/components/engine/docs/reference/api/docker_remote_api_v1.24.md b/components/engine/docs/reference/api/docker_remote_api_v1.24.md index 41f27acaf7..5baf5217c1 100644 --- a/components/engine/docs/reference/api/docker_remote_api_v1.24.md +++ b/components/engine/docs/reference/api/docker_remote_api_v1.24.md @@ -2672,6 +2672,32 @@ See the [image tarball format](#image-tarball-format) for more details. **Example response**: HTTP/1.1 200 OK + Content-Type: application/json + Transfer-Encoding: chunked + + {"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[= ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[== ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[=== ] 98.3 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[===== ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"} + ... + {"stream":"Loaded image: busybox:latest\n"} + +**Example response**: + +If the "quiet" query parameter is set to `true` / `1` (`?quiet=1`), progress +details are suppressed, and only a confirmation message is returned as plain text +once the action completes. + + HTTP/1.1 200 OK + Content-Length: 29 + Content-Type: text/plain; charset=utf-8 + + Loaded image: busybox:latest + +**Query parameters**: + +- **quiet** – Boolean value, suppress progress details during load. Defaults + to `0` / `false` if omitted. **Status codes**: diff --git a/components/engine/docs/reference/api/docker_remote_api_v1.25.md b/components/engine/docs/reference/api/docker_remote_api_v1.25.md index 3a26d41106..17aeb1882a 100644 --- a/components/engine/docs/reference/api/docker_remote_api_v1.25.md +++ b/components/engine/docs/reference/api/docker_remote_api_v1.25.md @@ -2678,6 +2678,32 @@ See the [image tarball format](#image-tarball-format) for more details. **Example response**: HTTP/1.1 200 OK + Content-Type: application/json + Transfer-Encoding: chunked + + {"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[= ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[== ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[=== ] 98.3 kB/1.293 MB","id":"8ac8bfaff55a"} + {"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[===== ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"} + ... + {"stream":"Loaded image: busybox:latest\n"} + +**Example response**: + +If the "quiet" query parameter is set to `true` / `1` (`?quiet=1`), progress +details are suppressed, and only a confirmation message is returned as plain text +once the action completes. + + HTTP/1.1 200 OK + Content-Length: 29 + Content-Type: text/plain; charset=utf-8 + + Loaded image: busybox:latest + +**Query parameters**: + +- **quiet** – Boolean value, suppress progress details during load. Defaults + to `0` / `false` if omitted. **Status codes**: