From d2382f7b96a58f141a83928f53930e9d946d6d04 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Sun, 1 Nov 2015 08:22:10 -0800 Subject: [PATCH] Remove old api docs that are no-longer appearing on docs-docker.com Signed-off-by: Mary Anthony --- docs/reference/api/docker_remote_api_v1.0.md | 993 ----------- docs/reference/api/docker_remote_api_v1.1.md | 1005 ------------ docs/reference/api/docker_remote_api_v1.10.md | 1354 --------------- docs/reference/api/docker_remote_api_v1.11.md | 1385 ---------------- docs/reference/api/docker_remote_api_v1.12.md | 1450 ----------------- docs/reference/api/docker_remote_api_v1.13.md | 1440 ---------------- docs/reference/api/docker_remote_api_v1.2.md | 1024 ------------ docs/reference/api/docker_remote_api_v1.3.md | 1110 ------------- docs/reference/api/docker_remote_api_v1.4.md | 1153 ------------- docs/reference/api/docker_remote_api_v1.5.md | 1159 ------------- docs/reference/api/docker_remote_api_v1.6.md | 1261 -------------- docs/reference/api/docker_remote_api_v1.7.md | 1249 -------------- docs/reference/api/docker_remote_api_v1.8.md | 1325 --------------- docs/reference/api/docker_remote_api_v1.9.md | 1358 --------------- 14 files changed, 17266 deletions(-) delete mode 100644 docs/reference/api/docker_remote_api_v1.0.md delete mode 100644 docs/reference/api/docker_remote_api_v1.1.md delete mode 100644 docs/reference/api/docker_remote_api_v1.10.md delete mode 100644 docs/reference/api/docker_remote_api_v1.11.md delete mode 100644 docs/reference/api/docker_remote_api_v1.12.md delete mode 100644 docs/reference/api/docker_remote_api_v1.13.md delete mode 100644 docs/reference/api/docker_remote_api_v1.2.md delete mode 100644 docs/reference/api/docker_remote_api_v1.3.md delete mode 100644 docs/reference/api/docker_remote_api_v1.4.md delete mode 100644 docs/reference/api/docker_remote_api_v1.5.md delete mode 100644 docs/reference/api/docker_remote_api_v1.6.md delete mode 100644 docs/reference/api/docker_remote_api_v1.7.md delete mode 100644 docs/reference/api/docker_remote_api_v1.8.md delete mode 100644 docs/reference/api/docker_remote_api_v1.9.md diff --git a/docs/reference/api/docker_remote_api_v1.0.md b/docs/reference/api/docker_remote_api_v1.0.md deleted file mode 100644 index 0ae774edd0..0000000000 --- a/docs/reference/api/docker_remote_api_v1.0.md +++ /dev/null @@ -1,993 +0,0 @@ - - -# Docker Remote API v1.0 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0" - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0" - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0" - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0" - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default -- **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. - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - - {{ TAR STREAM }} - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"" - } - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - - > **Example request**: - > - > POST /images/test/push HTTP/1.1 - > - > **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such image -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - -Query Parameters: - -- **t** – repository name to be applied to the resulting image in - case of success - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get default username and email - -`GET /auth` - -Get the default username and email - -**Example request**: - - GET /auth HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "username":"hannibal", - "email":"hannibal@a-team.com" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration and store i - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - > - > **Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this first version of the API, some of the endpoints, like /attach, -/pull or /push uses hijacking to transport stdin, stdout and stderr on -the same socket. This might change in the future. diff --git a/docs/reference/api/docker_remote_api_v1.1.md b/docs/reference/api/docker_remote_api_v1.1.md deleted file mode 100644 index 6f416de5d5..0000000000 --- a/docs/reference/api/docker_remote_api_v1.1.md +++ /dev/null @@ -1,1005 +0,0 @@ - - -# Docker Remote API v1.1 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0" - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0" - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0" - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0" - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default -- **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. - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"" - } - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - - > **Example request**: - > - > POST /images/test/push HTTP/1.1 - > - > **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such image -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - -Query Parameters: - -   - -- **t** – tag to be applied to the resulting image in case of - success - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get default username and email - -`GET /auth` - -Get the default username and email - -**Example request**: - - GET /auth HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "username":"hannibal", - "email":"hannibal@a-team.com" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration and store i - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. diff --git a/docs/reference/api/docker_remote_api_v1.10.md b/docs/reference/api/docker_remote_api_v1.10.md deleted file mode 100644 index 0119a51d25..0000000000 --- a/docs/reference/api/docker_remote_api_v1.10.md +++ /dev/null @@ -1,1354 +0,0 @@ - - -# Docker Remote API v1.10 - -## 1. Brief introduction - - - The Remote API has replaced rcli - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` - and `stderr` - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Query Parameters: - -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Image": "ubuntu", - "Volumes": {}, - "WorkingDir":"" - - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": null, - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -   - -- **ps\_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id` 's filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - 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 wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` -](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns - the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - - `DELETE /containers/(id*) -: Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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, Removes the container - even if it was running. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing - i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image - `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"] - "Image":"ubuntu", - "Volumes":null, - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - - `DELETE /images/(name*) -: Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -### 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#add)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 OK - 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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository - specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.11.md b/docs/reference/api/docker_remote_api_v1.11.md deleted file mode 100644 index 903bf5d067..0000000000 --- a/docs/reference/api/docker_remote_api_v1.11.md +++ /dev/null @@ -1,1385 +0,0 @@ - - -# Docker Remote API v1.11 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, `STDIN` - and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "VolumesFrom":"", - "WorkingDir":"", - "DisableNetwork": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Query Parameters: - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": null, - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -   - -- **follow** – 1/True/true or 0/False/false, return stream. - Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, if logs=true, prin - timestamps for every log line. Default false - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - 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 wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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, Removes the container - even if it was running. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"ubuntu", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "DisableNetwork": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - 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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.12.md b/docs/reference/api/docker_remote_api_v1.12.md deleted file mode 100644 index 9272346b13..0000000000 --- a/docs/reference/api/docker_remote_api_v1.12.md +++ /dev/null @@ -1,1450 +0,0 @@ - - -# Docker Remote API v1.12 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../articles/basics.md#bind-docker-to-another-hostport-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -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 -- **filters** – a JSON encoded value of the filters (a map[string][]string) - to process on the images list. - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "Domainname": "", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Query Parameters: - -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": null, - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -   - -- **follow** – 1/True/true or 0/False/false, return stream. - Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, if logs=true, prin - timestamps for every log line. Default false - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "Links":["redis3:redis"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - 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 wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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, Removes the container - even if it was running. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -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. Available filters: - - dangling=true -- **filter** - only return images with the specified name - - - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **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) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.13.md b/docs/reference/api/docker_remote_api_v1.13.md deleted file mode 100644 index a9b519d189..0000000000 --- a/docs/reference/api/docker_remote_api_v1.13.md +++ /dev/null @@ -1,1440 +0,0 @@ - - -# Docker Remote API v1.13 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../articles/basics.md#bind-docker-to-another-hostport-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "Domainname": "", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Query Parameters: - -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "Links":["redis3:redis"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - 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 wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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, Removes the container - even if it was running. Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -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. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **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) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.2.md b/docs/reference/api/docker_remote_api_v1.2.md deleted file mode 100644 index 678853eae1..0000000000 --- a/docs/reference/api/docker_remote_api_v1.2.md +++ /dev/null @@ -1,1024 +0,0 @@ - - -# Docker Remote API v1.2 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default -- **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. - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id":"b750fe79269d", - "Tag":["ubuntu:latest"], - "Created":1364102658, - "CreatedBy":"/bin/bash" - }, - { - "Id":"27cf78414709", - "Created":1364068391, - "CreatedBy":"" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - - > **Example request**: - > - > POST /images/test/push HTTP/1.1 - > {{ authConfig }} - > - > **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **204** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - {{ STREAM }} - -Query Parameters: - -- **t** – repository name to be applied to the resulting image in - case of success -- **remote** – resource to fetch, as URI - -Status Codes: - -- **200** – no error -- **500** – server error - -{{ STREAM }} is the raw text output of the build command. It uses the -HTTP Hijack method in order to stream. - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Status": "Login Succeeded" - } - -Status Codes: - -- **200** – no error -- **204** – no error -- **401** – unauthorized -- **403** – forbidden -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - -> docker -d -H="[tcp://192.168.1.9:2375](tcp://192.168.1.9:2375)" -> -api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.3.md b/docs/reference/api/docker_remote_api_v1.3.md deleted file mode 100644 index 1e2b4b3ce4..0000000000 --- a/docs/reference/api/docker_remote_api_v1.3.md +++ /dev/null @@ -1,1110 +0,0 @@ - - -# Docker Remote API v1.3 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "PID":"11935", - "Tty":"pts/2", - "Time":"00:00:00", - "Cmd":"sh" - }, - { - "PID":"12140", - "Tty":"pts/2", - "Time":"00:00:00", - "Cmd":"sleep" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - - > **Example request**: - > - > POST /images/test/push HTTP/1.1 - > {{ authConfig }} - > - > **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - The archive must include a file called Dockerfile at its root. I - may include any number of other files, which will be accessible in - the build context (See the ADD build command). - - The Content-type header should be set to "application/tar". - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "EventsListeners":"0", - "LXCVersion":"0.7.5", - "KernelVersion":"3.8.0-19-generic" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"create","id":"dfdf82bd3881","time":1374067924} - {"status":"start","id":"dfdf82bd3881","time":1374067924} - {"status":"stop","id":"dfdf82bd3881","time":1374067966} - {"status":"destroy","id":"dfdf82bd3881","time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - -> docker -d -H="192.168.1.9:2375" -api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.4.md b/docs/reference/api/docker_remote_api_v1.4.md deleted file mode 100644 index 6cedddf12e..0000000000 --- a/docs/reference/api/docker_remote_api_v1.4.md +++ /dev/null @@ -1,1153 +0,0 @@ - - -# Docker Remote API v1.4 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports":"", - "SizeRw":12288, - "SizeRootFs":0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Privileged": false, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"", - "WorkingDir":"" - - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **409** – conflict between containers and images -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict between containers and images -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - {{ authConfig }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} ... - -Status Codes: - -- **200** – no error :statuscode 404: no such image :statuscode - 500: server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - The archive must include a file called Dockerfile at its root. I - may include any number of other files, which will be accessible in - the build context (See the ADD build command). - - The Content-type header should be set to "application/tar". - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966} - {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.5.md b/docs/reference/api/docker_remote_api_v1.5.md deleted file mode 100644 index 76c6142c1c..0000000000 --- a/docs/reference/api/docker_remote_api_v1.5.md +++ /dev/null @@ -1,1159 +0,0 @@ - - -# Docker Remote API v1.5 - -# 1. Brief introduction - -- The Remote API is replacing rcli -- Default port in the docker daemon is 2375 -- The API tends to be REST, but for some complex commands, like attach - or pull, the HTTP connection is hijacked to transport stdout stdin - and stderr - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Privileged": false, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"", - "WorkingDir":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir":"" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles":[ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes":[ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path":"/dev", - "Kind":0 - }, - { - "Path":"/dev/kmsg", - "Kind":1 - }, - { - "Path":"/test", - "Kind":1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}] - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource":"test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/centos/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/fedora/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id":"b750fe79269d", - "Created":1364102658, - "CreatedBy":"/bin/bash" - }, - { - "Id":"27cf78414709", - "Created":1364068391, - "CreatedBy":"" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - The `X-Registry-Auth` header can be used to - include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged":"3e2f21a89f"}, - {"Deleted":"3e2f21a89f"}, - {"Deleted":"53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - The archive must include a file called Dockerfile at its root. I - may include any number of other files, which will be accessible in - the build context (See the ADD build command). - - The Content-type header should be set to "application/tar". - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** – remove intermediate containers after a successful build - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com", - "serveraddress":"https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "PortSpecs":["22"] - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966} - {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run`: - - - 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 - - If you are not in detached mode: - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.6.md b/docs/reference/api/docker_remote_api_v1.6.md deleted file mode 100644 index dd9c6ded9e..0000000000 --- a/docs/reference/api/docker_remote_api_v1.6.md +++ /dev/null @@ -1,1261 +0,0 @@ - - -# Docker Remote API v1.6 - -# 1. Brief introduction - - - The Remote API has replaced rcli - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` - and `stderr` - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "base:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "base:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "base:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "base:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "ExposedPorts":{}, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"base", - "Volumes":{}, - "VolumesFrom":"", - "WorkingDir":"" - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Query Parameters: - -   - -- **name** – container name to use - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - - **More Complex Example request, in 2 steps.** **First, use create to - expose a Private Port, which can be bound back to a Public Port a - startup**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Cmd":[ - "/usr/sbin/sshd","-D" - ], - "Image":"image-with-sshd", - "ExposedPorts":{"22/tcp":{}} - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - - **Second, start (using the ID returned above) the image we just - created, mapping the ssh port 22 to something on the host**: - - POST /containers/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }]} - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain; charset=utf-8 - Content-Length: 0 - - **Now you can ssh into your new container on port 11022.** - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "ExposedPorts": {}, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "base", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "ContainerIDFile": "", - "Privileged": false, - "PortBindings": {"22/tcp": [{HostIp:"", HostPort:""}]}, - "Links": [], - "PublishAllPorts": false - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -   - -- **signal** – Signal to send to the container (integer). When no - set, SIGKILL is assumed and the call will waits for the - container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/(format)` - -List images `format` could be json or viz (json default) - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"base", - "Tag":"ubuntu-12.10", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"base", - "Tag":"ubuntu-quantal", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] - -**Example request**: - - GET /images/viz HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nbase",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\nbase2",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\ntest",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by defaul - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=base HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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 - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/base/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "ExposedPorts":{}, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"base", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/base/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} ... - - > The `X-Registry-Auth` header can be used to - > include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error :statuscode 404: no such image :statuscode - 500: server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com) - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] - - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - - {{ STREAM }} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - The archive must include a file called Dockerfile at its root. I - may include any number of other files, which will be accessible in - the build context (See the ADD build command). - - The Content-type header should be set to "application/tar". - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Cmd": ["cat", "/world"], - "ExposedPorts":{"22/tcp":{}} - } - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.7.md b/docs/reference/api/docker_remote_api_v1.7.md deleted file mode 100644 index 8a73342667..0000000000 --- a/docs/reference/api/docker_remote_api_v1.7.md +++ /dev/null @@ -1,1249 +0,0 @@ - - -# Docker Remote API v1.7 - -# 1. Brief introduction - - - The Remote API has replaced rcli - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` - and `stderr` - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "base:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "base:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "base:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "base:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"base", - "Volumes":{ - "/tmp": {} - }, - "VolumesFrom":"", - "WorkingDir":"", - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **config** – the container's configuration - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "base", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "Privileged":false, - "PublishAllPorts":false - } - - Binds need to reference Volumes that were defined during container - creation. - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.7.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=base HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/base/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"base", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/base/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - Request Headers: - -   - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {{ STREAM }} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image - - Request Headers: - -   - -- **Content-type** – should be set to - `"application/tar"`. - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") -- **run** – config automatically applied when the image is run. - (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]}) - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - :statuscode 200: no error - :statuscode 500: server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -**Example request** - - POST /images/load - - Tarball in body - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - - :statuscode 200: no error - :statuscode 500: server error - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - -- 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 - -- If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.8.md b/docs/reference/api/docker_remote_api_v1.8.md deleted file mode 100644 index 62324df8e1..0000000000 --- a/docs/reference/api/docker_remote_api_v1.8.md +++ /dev/null @@ -1,1325 +0,0 @@ - - -# Docker Remote API v1.8 - -# 1. Brief introduction - - - The Remote API has replaced rcli - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` - and `stderr` - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "base:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "base:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "base:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "base:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"base", - "Volumes":{ - "/tmp": {} - }, - "VolumesFrom":"", - "WorkingDir":"", - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -   - -- **Hostname** – Container host name -- **User** – Username or UID -- **Memory** – Memory Limit in bytes -- **CpuShares** – CPU shares (relative weight) -- **AttachStdin** – 1/True/true or 0/False/false, attach to - standard input. Default false -- **AttachStdout** – 1/True/true or 0/False/false, attach to - standard output. Default false -- **AttachStderr** – 1/True/true or 0/False/false, attach to - standard error. Default false -- **Tty** – 1/True/true or 0/False/false, allocate a pseudo-tty. - Default false -- **OpenStdin** – 1/True/true or 0/False/false, keep stdin open - even if not attached. Default false - -Query Parameters: - -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "base", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": null, - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **Binds** – Create a bind mount to a directory or file with - [host-path]:[container-path]:[rw|ro]. If a directory - "container-path" is missing, then docker creates a new volume. -- **LxcConf** – Map of custom lxc options -- **PortBindings** – Expose ports from the container, optionally - publishing them via the HostPort flag -- **PublishAllPorts** – 1/True/true or 0/False/false, publish all - exposed ports to the host interfaces. Default false -- **Privileged** – 1/True/true or 0/False/false, give extended - privileges to this container. Default false - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](docker_remote_api_v1.9.md#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=base HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/base/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"base", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/base/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - Request Headers: - -   - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image - - Request Headers: - -   - -- **Content-type** – should be set to - `"application/tar"`. -- **X-Registry-Auth** – base64-encoded AuthConfig objec - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream - - {"Id": "596069db4bf5"} - -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)>") -- **run** – config automatically applied when the image is run. - (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]}) - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, -or via polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run`: - - - 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 - - - If you are not in detached mode: - - 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.9.md b/docs/reference/api/docker_remote_api_v1.9.md deleted file mode 100644 index ae18deb4c6..0000000000 --- a/docs/reference/api/docker_remote_api_v1.9.md +++ /dev/null @@ -1,1358 +0,0 @@ - - -# Docker Remote API v1.9 - -# 1. Brief introduction - - - The Remote API has replaced rcli - - The daemon listens on `unix:///var/run/docker.sock` but you can bind - Docker to another host/port or a Unix socket. - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` - and `stderr` - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers. - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "base:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "base:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "base:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "base:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -   - -- **all** – 1/True/true or 0/False/false, Show all containers. - 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: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"base", - "Volumes":{ - "/tmp": {} - }, - "VolumesFrom":"", - "WorkingDir":"", - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -   - -- **Hostname** – Container host name -- **User** – Username or UID -- **Memory** – Memory Limit in bytes -- **CpuShares** – CPU shares (relative weight) -- **AttachStdin** – 1/True/true or 0/False/false, attach to - standard input. Default false -- **AttachStdout** – 1/True/true or 0/False/false, attach to - standard output. Default false -- **AttachStderr** – 1/True/true or 0/False/false, attach to - standard error. Default false -- **Tty** – 1/True/true or 0/False/false, allocate a pseudo-tty. - Default false -- **OpenStdin** – 1/True/true or 0/False/false, keep stdin open - even if not attached. Default false - -Query Parameters: - -   - -- **name** – Assign the specified name to the container. Mus - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id)/json` - -Return low-level information on the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "base", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": null, - "PublishAllPorts": false - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id)/top` - -List processes running inside the container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles": [ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes": [ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - -Query Parameters: - -- **ps_args** – ps arguments to use (e.g., aux) - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id)/start` - -Start the container `id` - -**Example request**: - - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false - } - -**Example response**: - - HTTP/1.1 204 No Content - Content-Type: text/plain - -Json Parameters: - -   - -- **Binds** – Create a bind mount to a directory or file with - [host-path]:[container-path]:[rw|ro]. If a directory - "container-path" is missing, then docker creates a new volume. -- **LxcConf** – Map of custom lxc options -- **PortBindings** – Expose ports from the container, optionally - publishing them via the HostPort flag -- **PublishAllPorts** – 1/True/true or 0/False/false, publish all - exposed ports to the host interfaces. Default false -- **Privileged** – 1/True/true or 0/False/false, give extended - privileges to this container. Default false - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 OK - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - 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 wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -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 -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - 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 - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create`](#create-a-container), the - stream is the raw data from the process PTY and client's stdin. When - the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1) - -### Attach to a container (websocket) - -`GET /containers/(id)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **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 -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - 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 - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - -### Create an image - -`POST /images/create` - -Create an image, either by pull it from the registry or by importing i - -**Example request**: - - POST /images/create?fromImage=base HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -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: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Insert a file in an image - -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - -**Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} - {"error":"Invalid..."} - ... - -Query Parameters: - -- **url** – The url from where the file is taken -- **path** – The path where the file is stored - -Status Codes: - -- **200** – no error -- **500** – server error - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/base/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"], - "Dns":null, - "Image":"base", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/base/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - Request Headers: - -   - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 OK - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name*) -: Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_trusted": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile - -`POST /build` - -Build an image from Dockerfile using a POST body. - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#add)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – build source URI (git or HTTPS/HTTP) -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** – Remove intermediate containers after a successful build - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the Docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "DisableNetwork": false, - "ExposedPorts":{ - "22/tcp": {} - } - } - -**Example response**: - - 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)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -Here are the steps of `docker run` : - - - 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 - - - If you are not in detached mode: - -- 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 - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -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. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors