From f304d4b190276939c9aff2090925342d16c7405e Mon Sep 17 00:00:00 2001 From: "Ted M. Young" Date: Fri, 5 Sep 2014 17:42:51 -0700 Subject: [PATCH] Misc. fixes and formatting clean-up Cleaned up and corrected some invalid "example responses". Added some missing double-quotes for examples that resulted in invalid JSON. Other general cleanup of stray characters and typos. Docker-DCO-1.1-Signed-off-by: Ted M. Young (github: SvenDowideit) --- .../reference/api/docker_remote_api_v1.14.md | 147 ++++++------------ .../reference/api/docker_remote_api_v1.15.md | 109 ++++--------- 2 files changed, 75 insertions(+), 181 deletions(-) diff --git a/docs/sources/reference/api/docker_remote_api_v1.14.md b/docs/sources/reference/api/docker_remote_api_v1.14.md index 28f71bb62..793133a6f 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.14.md +++ b/docs/sources/reference/api/docker_remote_api_v1.14.md @@ -79,15 +79,11 @@ List containers Query Parameters: - **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes + Only running containers are shown by default (i.e., this defaults to false) +- **limit** – Show `limit` last created containers, include non-running ones. +- **since** – Show only containers created since Id, include non-running ones. +- **before** – Show only containers created before Id, include non-running ones. +- **size** – 1/True/true or 0/False/false, Show the containers sizes Status Codes: @@ -139,7 +135,7 @@ Create a container **Example response**: - HTTP/1.1 201 OK + HTTP/1.1 201 Created Content-Type: application/json { @@ -149,23 +145,17 @@ Create a container Json Parameters: -   - - **RestartPolicy** – The behavior to apply when the container exits. The value is an object with a `Name` property of either `"always"` to always restart or `"on-failure"` to restart only when the container exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` controls the number of times to retry before giving up. The default is not to restart. (optional) - - **config** – the container's configuration Query Parameters: -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. +- **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. Status Codes: @@ -299,8 +289,6 @@ List processes running inside the container `id` Query Parameters: -   - - **ps_args** – ps arguments to use (e.g., aux) Status Codes: @@ -328,14 +316,13 @@ Get stdout and stderr logs from the container ``id`` Query Parameters: -   - - **follow** – 1/True/true or 0/False/false, return stream. Default false - **stdout** – 1/True/true or 0/False/false, show stdout log. Default false - **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, print timestamps for - every log line. Default false -- **tail** – Output specified number of lines at the end of logs: `all` or ``. Default all +- **timestamps** – 1/True/true or 0/False/false, print timestamps for every + log line. Default false +- **tail** – Output specified number of lines at the end of logs: `all` or + ``. Default all Status Codes: @@ -422,19 +409,16 @@ Start the container `id` "Privileged":false, "Dns": ["8.8.8.8"], "VolumesFrom": ["parent", "other:ro"], - "CapAdd: ["NET_ADMIN"], - "CapDrop: ["MKNOD"] + "CapAdd": ["NET_ADMIN"], + "CapDrop": ["MKNOD"] } **Example response**: - HTTP/1.1 204 No Conten - Content-Type: text/plain + HTTP/1.1 204 No Content Json Parameters: -   - - **hostConfig** – the container's host configuration (optional) Status Codes: @@ -456,12 +440,10 @@ Stop the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **t** – number of seconds to wait before killing the container Status Codes: @@ -483,12 +465,10 @@ Restart the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **t** – number of seconds to wait before killing the container Status Codes: @@ -509,12 +489,12 @@ Kill the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters - **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. + When not set, SIGKILL is assumed and the call will wait for the container to exit. Status Codes: @@ -534,7 +514,7 @@ Pause the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Status Codes: @@ -554,7 +534,7 @@ Unpause the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Status Codes: @@ -581,18 +561,14 @@ Attach to the container `id` Query Parameters: -   - -- **logs** – 1/True/true or 0/False/false, return logs. Defaul - false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false +- **logs** – 1/True/true or 0/False/false, return logs. Default false +- **stream** – 1/True/true or 0/False/false, return stream. Default false +- **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. + Default false - **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false + stdout log, if stream=true, attach to stdout. Default false - **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false + stderr log, if stream=true, attach to stderr. Default false Status Codes: @@ -643,7 +619,7 @@ Status Codes: 2. chose stdout or stderr depending on the first byte 3. Extract the frame size from the last 4 byets 4. Read the extracted size and output it on the correct output - 5. Goto 1) + 5. Goto 1 ### Wait a container @@ -680,12 +656,10 @@ Remove the container `id` from the filesystem **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **v** – 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false - **force** - 1/True/true or 0/False/false, Kill then remove the container. @@ -769,18 +743,14 @@ Status Codes: Query Parameters: -   - - **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. - - +- **filters** – a json encoded value of the filters (a map[string][string]) to process on the images list. ### Create an image `POST /images/create` -Create an image, either by pull it from the registry or by importing i +Create an image, either by pulling it from the registry or by importing it **Example request**: @@ -802,19 +772,15 @@ Create an image, either by pull it from the registry or by importing i Query Parameters: -   - - **fromImage** – name of the image to pull - **fromSrc** – source to import, - means stdin - **repo** – repository - **tag** – tag - **registry** – the registry to pull from - Request Headers: +Request Headers: -   - -- **X-Registry-Auth** – base64-encoded AuthConfig objec +- **X-Registry-Auth** – base64-encoded AuthConfig object Status Codes: @@ -938,16 +904,11 @@ Push the image `name` on the registry Query Parameters: -   - - **tag** – the tag to associate with the image on the registry, optional - Request Headers: +Request Headers: -   - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. +- **X-Registry-Auth** – include a base64-encoded AuthConfig object. Status Codes: @@ -971,8 +932,6 @@ Tag the image `name` into a repository Query Parameters: -   - - **repo** – The repository to tag in - **force** – 1/True/true or 0/False/false, default false @@ -1007,8 +966,6 @@ Remove the image `name` from the filesystem Query Parameters: -   - - **force** – 1/True/true or 0/False/false, default false - **noprune** – 1/True/true or 0/False/false, default false @@ -1065,8 +1022,6 @@ Search for an image on [Docker Hub](https://hub.docker.com). Query Parameters: -   - - **term** – term to search Status Codes: @@ -1107,10 +1062,8 @@ Build an image from Dockerfile via stdin Query Parameters: -   - - **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success + the resulting image in case of success - **q** – suppress verbose build output - **nocache** – do not use the cache when building the image - **rm** - remove intermediate containers after a successful build (default behavior) @@ -1118,10 +1071,7 @@ Query Parameters: Request Headers: -   - -- **Content-type** – should be set to - `"application/tar"`. +- **Content-type** – should be set to `"application/tar"`. - **X-Registry-Config** – base64-encoded ConfigFile objec Status Codes: @@ -1234,6 +1184,7 @@ Ping the docker server **Example response**: HTTP/1.1 200 OK + Content-Type: text/plain OK @@ -1284,27 +1235,23 @@ Create a new image from a container's changes **Example response**: - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream + HTTP/1.1 201 Created + Content-Type: application/vnd.docker.raw-stream {"Id":"596069db4bf5"} Json Parameters: - - - **config** - the container's configuration Query Parameters: -   - - **container** – source container - **repo** – repository - **tag** – tag - **m** – commit message - **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") + <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") Status Codes: @@ -1335,8 +1282,6 @@ via polling (using since) Query Parameters: -   - - **since** – timestamp used for polling - **until** – timestamp used for polling @@ -1417,22 +1362,22 @@ the root that contains a list of repository and tag names mapped to layer IDs. ## 3.1 Inside `docker run` -Here are the steps of `docker run`: +Here are what the command line `docker run` does via the API: - Create the container - If the status code is 404, it means the image doesn't exists: -- Try to pull i -- Then retry to create the container + - Try to pull it + - Then retry to create the container - Start the container - If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and + - Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1 - If in detached mode or only stdin is attached: -- Display the container's id + - Display the container's id ## 3.2 Hijacking @@ -1442,6 +1387,6 @@ stdout and stderr on the same socket. This might change in the future. ## 3.3 CORS Requests To enable cross origin requests to the remote api add the flag -"–api-enable-cors" when running docker in daemon mode. +"--api-enable-cors" when running docker in daemon mode. $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/sources/reference/api/docker_remote_api_v1.15.md b/docs/sources/reference/api/docker_remote_api_v1.15.md index 2f2e77b1e..3d3e0bb19 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.15.md +++ b/docs/sources/reference/api/docker_remote_api_v1.15.md @@ -78,10 +78,8 @@ List containers Query Parameters: -   - - **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul + Only running containers are shown by default (i.e., this defaults to false) - **limit** – Show `limit` last created containers, include non-running ones. - **since** – Show only containers created since Id, include @@ -141,7 +139,7 @@ Create a container **Example response**: - HTTP/1.1 201 OK + HTTP/1.1 201 Created Content-Type: application/json { @@ -151,23 +149,18 @@ Create a container Json Parameters: -   - - **RestartPolicy** – The behavior to apply when the container exits. The value is an object with a `Name` property of either `"always"` to always restart or `"on-failure"` to restart only when the container exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` controls the number of times to retry before giving up. The default is not to restart. (optional) - - **config** – the container's configuration Query Parameters: -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. +- **name** – Assign the specified name to the container. Must + match `/?[a-zA-Z0-9_-]+`. Status Codes: @@ -301,8 +294,6 @@ List processes running inside the container `id` Query Parameters: -   - - **ps_args** – ps arguments to use (e.g., aux) Status Codes: @@ -330,8 +321,6 @@ Get stdout and stderr logs from the container ``id`` Query Parameters: -   - - **follow** – 1/True/true or 0/False/false, return stream. Default false - **stdout** – 1/True/true or 0/False/false, show stdout log. Default false - **stderr** – 1/True/true or 0/False/false, show stderr log. Default false @@ -424,19 +413,16 @@ Start the container `id` "Privileged":false, "Dns": ["8.8.8.8"], "VolumesFrom": ["parent", "other:ro"], - "CapAdd: ["NET_ADMIN"], - "CapDrop: ["MKNOD"] + "CapAdd": ["NET_ADMIN"], + "CapDrop": ["MKNOD"] } **Example response**: - HTTP/1.1 204 No Conten - Content-Type: text/plain + HTTP/1.1 204 No Content Json Parameters: -   - - **hostConfig** – the container's host configuration (optional) Status Codes: @@ -458,12 +444,10 @@ Stop the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **t** – number of seconds to wait before killing the container Status Codes: @@ -485,12 +469,10 @@ Restart the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **t** – number of seconds to wait before killing the container Status Codes: @@ -511,7 +493,7 @@ Kill the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters @@ -536,7 +518,7 @@ Pause the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Status Codes: @@ -556,7 +538,7 @@ Unpause the container `id` **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Status Codes: @@ -583,10 +565,7 @@ Attach to the container `id` Query Parameters: -   - -- **logs** – 1/True/true or 0/False/false, return logs. Defaul - false +- **logs** – 1/True/true or 0/False/false, return logs. Default false - **stream** – 1/True/true or 0/False/false, return stream. Default false - **stdin** – 1/True/true or 0/False/false, if stream=true, attach @@ -645,7 +624,7 @@ Status Codes: 2. chose stdout or stderr depending on the first byte 3. Extract the frame size from the last 4 byets 4. Read the extracted size and output it on the correct output - 5. Goto 1) + 5. Goto 1 ### Wait a container @@ -682,12 +661,10 @@ Remove the container `id` from the filesystem **Example response**: - HTTP/1.1 204 OK + HTTP/1.1 204 No Content Query Parameters: -   - - **v** – 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false - **force** - 1/True/true or 0/False/false, Kill then remove the container. @@ -771,18 +748,14 @@ Status Codes: Query Parameters: -   - - **all** – 1/True/true or 0/False/false, default false - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. - - ### Create an image `POST /images/create` -Create an image, either by pull it from the registry or by importing i +Create an image, either by pulling it from the registry or by importing it **Example request**: @@ -804,8 +777,6 @@ Create an image, either by pull it from the registry or by importing i Query Parameters: -   - - **fromImage** – name of the image to pull - **fromSrc** – source to import, - means stdin - **repo** – repository @@ -814,9 +785,7 @@ Query Parameters: Request Headers: -   - -- **X-Registry-Auth** – base64-encoded AuthConfig objec +- **X-Registry-Auth** – base64-encoded AuthConfig object Status Codes: @@ -940,13 +909,9 @@ Push the image `name` on the registry Query Parameters: -   - - **tag** – the tag to associate with the image on the registry, optional - Request Headers: - -   +Request Headers: - **X-Registry-Auth** – include a base64-encoded AuthConfig object. @@ -973,8 +938,6 @@ Tag the image `name` into a repository Query Parameters: -   - - **repo** – The repository to tag in - **force** – 1/True/true or 0/False/false, default false @@ -1009,8 +972,6 @@ Remove the image `name` from the filesystem Query Parameters: -   - - **force** – 1/True/true or 0/False/false, default false - **noprune** – 1/True/true or 0/False/false, default false @@ -1067,8 +1028,6 @@ Search for an image on [Docker Hub](https://hub.docker.com). Query Parameters: -   - - **term** – term to search Status Codes: @@ -1109,8 +1068,6 @@ Build an image from Dockerfile via stdin Query Parameters: -   - - **t** – repository name (and optionally a tag) to be applied to the resulting image in case of success - **q** – suppress verbose build output @@ -1120,10 +1077,7 @@ Query Parameters: Request Headers: -   - -- **Content-type** – should be set to - `"application/tar"`. +- **Content-type** – should be set to `"application/tar"`. - **X-Registry-Config** – base64-encoded ConfigFile objec Status Codes: @@ -1236,6 +1190,7 @@ Ping the docker server **Example response**: HTTP/1.1 200 OK + Content-Type: text/plain OK @@ -1286,27 +1241,23 @@ Create a new image from a container's changes **Example response**: - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream + HTTP/1.1 201 Created + Content-Type: application/vnd.docker.raw-stream {"Id":"596069db4bf5"} Json Parameters: - - - **config** - the container's configuration Query Parameters: -   - - **container** – source container - **repo** – repository - **tag** – tag - **m** – commit message - **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") + <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") Status Codes: @@ -1337,8 +1288,6 @@ via polling (using since) Query Parameters: -   - - **since** – timestamp used for polling - **until** – timestamp used for polling @@ -1377,7 +1326,7 @@ Status Codes: - **200** – no error - **500** – server error -### Get a tarball containing of images. +### Get a tarball containing all images. `GET /images/get` @@ -1453,13 +1402,13 @@ the root that contains a list of repository and tag names mapped to layer IDs. ## 3.1 Inside `docker run` -Here are the steps of `docker run`: +Here are what the command line `docker run` does via the API: - Create the container -- If the status code is 404, it means the image doesn't exists: -- Try to pull i -- Then retry to create the container +- If the status code is 404, it means the image doesn't exist: + - Try to pull it + - Then retry to create the container - Start the container @@ -1478,6 +1427,6 @@ stdout and stderr on the same socket. This might change in the future. ## 3.3 CORS Requests To enable cross origin requests to the remote api add the flag -"–api-enable-cors" when running docker in daemon mode. +"--api-enable-cors" when running docker in daemon mode. $ docker -d -H="192.168.1.9:2375" --api-enable-cors