Docker Cookbook

Action on images
HTTP method
URI
List images
GET
/images/json
Create an image
POST
/images/create
Tag an image into a repository
POST
/images/(name)/tag
Remove an image
DELETE
/images/(name)
Search images
GET
/images/search
For example, let’s download the Ubuntu 14.04 image from the public registry (a.k.a.
Docker Hub), create a container from that image, and start it. Remove it and then
remove the image. Note that in this toy example, running the container will cause it
to exit immediately because you are not passing any commands:
$ curl -X POST -d "fromImage=ubuntu" -d "tag=14.04"
http://127.0.0.1:2375/images/create
$ curl -X POST -H 'Content-Type: application/json'
-d '{"Image":"ubuntu:14.04"}'
http://127.0.0.1:2375/containers/create
{"Id":"6b6bd46f483a5704d4bced62ff58a0ac5758fb0875ec881fa68f0e...",\
"Warnings":null}
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS ...
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS ...
6b6bd46f483a ubuntu:14.04 "/bin/bash" 16 seconds ago ...
$ curl -X POST http://127.0.0.1:2375/containers/6b6bd46f483a/start
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED ...
6b6bd46f483a ubuntu:14.04 "/bin/bash" About a minute ago ...
Now let’s clean things up:
$ curl -X DELETE http://127.0.0.1:2375/containers/6b6bd46f483a
$ curl -X DELETE http://127.0.0.1:2375/images/04c5d3b7b065
[{"Untagged":"ubuntu:14.04"}
,{"Deleted":"04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2"}
120 | Chapter 4: Docker Configuration and Development

---

,{"Deleted":"d735006ad9c1b1563e021d7a4fecfd75ed36d4384e2a1c42e78d8261b83d6271"}
,{"Deleted":"70c8faa62a44b9f6a70ec3a018ec14ec95717ebed2016430e57fec1abc90a879"}
,{"Deleted":"c7b7c64195686444123ef370322b5270b098c77dc2d62208e8a9ce28a11a63f9"}
,{"Deleted":"511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158"}
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS ...
$ docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
After enabling remote API access, you can set the 
DOCKER_HOST
variable to its HTTP endpoint. This relieves you from passing it to
the 
docker
command as an 
-H
option. For example, instead of
docker -H http://127.0.0.1:2375 ps
, you can use 
export
DOCKER_HOST=tcp://127.0.0.1:2375
and you will be able to sim‐
ply use 
docker ps
.
Discussion
Although you can use 
curl
or write your own client, existing Docker clients like
docker-py
(see 
Recipe 4.10
) can ease calling the API.
The list of APIs presented in 
Table 4-1
 and 
Table 4-2
 is not exhaustive, and you
should check the complete API 
documentation
for all API calls, query parameters,
and response examples.