Browse Source

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 <github@gone.nl>
Sebastiaan van Stijn 9 years ago
parent
commit
d13ed38471

+ 1 - 0
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
 

+ 26 - 0
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**:
 

+ 26 - 0
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**:
 

+ 26 - 0
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**: