1. docker
  2. Commit e4cb83c50e554bfd8ae3e0a1f2be4f0fb661861d
Browse code

Bump api version and update docs

Johannes 'fish' Ziemke authored on 2013/12/03 03:23:54
Showing 4 changed files
api.go
History View file @ e4cb83c
... ... 
@@ -26,7 +26,7 @@ import (
26 26 
 )
27 27
28 28 
 const (
29 
-	APIVERSION        = 1.7
29 
+	APIVERSION        = 1.8
30 30 
 	DEFAULTHTTPHOST   = "127.0.0.1"
31 31 
 	DEFAULTHTTPPORT   = 4243
32 32 
 	DEFAULTUNIXSOCKET = "/var/run/docker.sock"
docs/sources/api/docker_remote_api.rst
History View file @ e4cb83c
... ... 
@@ -34,6 +34,24 @@ Calling /images/<name>/insert is the same as calling
34 34 
 You can still call an old version of the api using
35 35 
 /v1.0/images/<name>/insert
36 36
37 
+
38 
+v1.8
39 
+****
40 
+
41 
+Full Documentation
42 
+------------------
43 
+
44 
+:doc:`docker_remote_api_v1.8`
45 
+
46 
+What's new
47 
+----------
48 
+
49 
+.. http:post:: /build
50 
+
51 
+   **New!** This endpoint now returns build status as json stream. In case
52 
+   of a build error, it returns the exit status of the failed command.
53 
+
54 
+
37 55 
 v1.7
38 56 
 ****
39 57
... ... 
@@ -138,11 +156,6 @@ What's new
138 138 
    This URI no longer exists.  The ``images -viz`` output is now generated in
139 139 
    the client, using the ``/images/json`` data.
140 140
141 
-.. http:post:: /build
142 
-
143 
-   **New!** This endpoint now returns build status as json stream. In case
144 
-   of a build error, it returns the exit status of the failed command.
145 
-
146 141 
 v1.6
147 142 
 ****
148 143
docs/sources/api/docker_remote_api_v1.7.rst
History View file @ e4cb83c
... ... 
@@ -992,9 +992,7 @@ Build an image from Dockerfile via stdin
992 992 
       HTTP/1.1 200 OK
993 993 
       Content-Type: application/json
994 994
995 
-      {"status":"Step 1..."}
996 
-      {"status":"..."}
997 
-      {"error":"Error...", "errorDetail":{"code": 123, "message": "Error..."}}
995 
+      {{ STREAM }}
998 996
999 997 
    The stream must be a tar archive compressed with one of the
1000 998 
    following algorithms: identity (no compression), gzip, bzip2,
docs/sources/api/docker_remote_api_v1.8.rst
History View file @ e4cb83c
1001 999 
new file mode 100644
... ... 
@@ -0,0 +1,1257 @@
0 
+:title: Remote API v1.8
1 
+:description: API Documentation for Docker
2 
+:keywords: API, Docker, rcli, REST, documentation
3 
+
4 
+:orphan:
5 
+
6 
+======================
7 
+Docker Remote API v1.8
8 
+======================
9 
+
10 
+.. contents:: Table of Contents
11 
+
12 
+1. Brief introduction
13 
+=====================
14 
+
15 
+- The Remote API has replaced rcli
16 
+- The daemon listens on ``unix:///var/run/docker.sock``, but you can
17 
+  :ref:`bind_docker`.
18 
+- The API tends to be REST, but for some complex commands, like
19 
+  ``attach`` or ``pull``, the HTTP connection is hijacked to transport
20 
+  ``stdout, stdin`` and ``stderr``
21 
+
22 
+2. Endpoints
23 
+============
24 
+
25 
+2.1 Containers
26 
+--------------
27 
+
28 
+List containers
29 
+***************
30 
+
31 
+.. http:get:: /containers/json
32 
+
33 
+	List containers
34 
+
35 
+	**Example request**:
36 
+
37 
+	.. sourcecode:: http
38 
+
39 
+	   GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
40 
+
41 
+	**Example response**:
42 
+
43 
+	.. sourcecode:: http
44 
+
45 
+	   HTTP/1.1 200 OK
46 
+	   Content-Type: application/json
47 
+
48 
+	   [
49 
+		{
50 
+			"Id": "8dfafdbc3a40",
51 
+			"Image": "base:latest",
52 
+			"Command": "echo 1",
53 
+			"Created": 1367854155,
54 
+			"Status": "Exit 0",
55 
+			"Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
56 
+			"SizeRw":12288,
57 
+			"SizeRootFs":0
58 
+		},
59 
+		{
60 
+			"Id": "9cd87474be90",
61 
+			"Image": "base:latest",
62 
+			"Command": "echo 222222",
63 
+			"Created": 1367854155,
64 
+			"Status": "Exit 0",
65 
+			"Ports":[],
66 
+			"SizeRw":12288,
67 
+			"SizeRootFs":0
68 
+		},
69 
+		{
70 
+			"Id": "3176a2479c92",
71 
+			"Image": "base:latest",
72 
+			"Command": "echo 3333333333333333",
73 
+			"Created": 1367854154,
74 
+			"Status": "Exit 0",
75 
+			"Ports":[],
76 
+			"SizeRw":12288,
77 
+			"SizeRootFs":0
78 
+		},
79 
+		{
80 
+			"Id": "4cb07b47f9fb",
81 
+			"Image": "base:latest",
82 
+			"Command": "echo 444444444444444444444444444444444",
83 
+			"Created": 1367854152,
84 
+			"Status": "Exit 0",
85 
+			"Ports":[],
86 
+			"SizeRw":12288,
87 
+			"SizeRootFs":0
88 
+		}
89 
+	   ]
90 
+
91 
+	:query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
92 
+	:query limit: Show ``limit`` last created containers, include non-running ones.
93 
+	:query since: Show only containers created since Id, include non-running ones.
94 
+	:query before: Show only containers created before Id, include non-running ones.
95 
+	:query size: 1/True/true or 0/False/false, Show the containers sizes
96 
+	:statuscode 200: no error
97 
+	:statuscode 400: bad parameter
98 
+	:statuscode 500: server error
99 
+
100 
+
101 
+Create a container
102 
+******************
103 
+
104 
+.. http:post:: /containers/create
105 
+
106 
+	Create a container
107 
+
108 
+	**Example request**:
109 
+
110 
+	.. sourcecode:: http
111 
+
112 
+	   POST /containers/create HTTP/1.1
113 
+	   Content-Type: application/json
114 
+
115 
+	   {
116 
+		"Hostname":"",
117 
+		"User":"",
118 
+		"Memory":0,
119 
+		"MemorySwap":0,
120 
+		"AttachStdin":false,
121 
+		"AttachStdout":true,
122 
+		"AttachStderr":true,
123 
+		"PortSpecs":null,
124 
+		"Privileged": false,
125 
+		"Tty":false,
126 
+		"OpenStdin":false,
127 
+		"StdinOnce":false,
128 
+		"Env":null,
129 
+		"Cmd":[
130 
+			"date"
131 
+		],
132 
+		"Dns":null,
133 
+		"Image":"base",
134 
+		"Volumes":{},
135 
+		"VolumesFrom":"",
136 
+		"WorkingDir":""
137 
+
138 
+	   }
139 
+
140 
+	**Example response**:
141 
+
142 
+	.. sourcecode:: http
143 
+
144 
+	   HTTP/1.1 201 OK
145 
+	   Content-Type: application/json
146 
+
147 
+	   {
148 
+		"Id":"e90e34656806"
149 
+		"Warnings":[]
150 
+	   }
151 
+
152 
+	:jsonparam config: the container's configuration
153 
+	:statuscode 201: no error
154 
+	:statuscode 404: no such container
155 
+	:statuscode 406: impossible to attach (container not running)
156 
+	:statuscode 500: server error
157 
+
158 
+
159 
+Inspect a container
160 
+*******************
161 
+
162 
+.. http:get:: /containers/(id)/json
163 
+
164 
+	Return low-level information on the container ``id``
165 
+
166 
+	**Example request**:
167 
+
168 
+	.. sourcecode:: http
169 
+
170 
+	   GET /containers/4fa6e0f0c678/json HTTP/1.1
171 
+
172 
+	**Example response**:
173 
+
174 
+	.. sourcecode:: http
175 
+
176 
+	   HTTP/1.1 200 OK
177 
+	   Content-Type: application/json
178 
+
179 
+	   {
180 
+			"Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
181 
+			"Created": "2013-05-07T14:51:42.041847+02:00",
182 
+			"Path": "date",
183 
+			"Args": [],
184 
+			"Config": {
185 
+				"Hostname": "4fa6e0f0c678",
186 
+				"User": "",
187 
+				"Memory": 0,
188 
+				"MemorySwap": 0,
189 
+				"AttachStdin": false,
190 
+				"AttachStdout": true,
191 
+				"AttachStderr": true,
192 
+				"PortSpecs": null,
193 
+				"Tty": false,
194 
+				"OpenStdin": false,
195 
+				"StdinOnce": false,
196 
+				"Env": null,
197 
+				"Cmd": [
198 
+					"date"
199 
+				],
200 
+				"Dns": null,
201 
+				"Image": "base",
202 
+				"Volumes": {},
203 
+				"VolumesFrom": "",
204 
+				"WorkingDir":""
205 
+
206 
+			},
207 
+			"State": {
208 
+				"Running": false,
209 
+				"Pid": 0,
210 
+				"ExitCode": 0,
211 
+				"StartedAt": "2013-05-07T14:51:42.087658+02:01360",
212 
+				"Ghost": false
213 
+			},
214 
+			"Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
215 
+			"NetworkSettings": {
216 
+				"IpAddress": "",
217 
+				"IpPrefixLen": 0,
218 
+				"Gateway": "",
219 
+				"Bridge": "",
220 
+				"PortMapping": null
221 
+			},
222 
+			"SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
223 
+			"ResolvConfPath": "/etc/resolv.conf",
224 
+			"Volumes": {}
225 
+	   }
226 
+
227 
+	:statuscode 200: no error
228 
+	:statuscode 404: no such container
229 
+	:statuscode 500: server error
230 
+
231 
+
232 
+List processes running inside a container
233 
+*****************************************
234 
+
235 
+.. http:get:: /containers/(id)/top
236 
+
237 
+	List processes running inside the container ``id``
238 
+
239 
+	**Example request**:
240 
+
241 
+	.. sourcecode:: http
242 
+
243 
+	   GET /containers/4fa6e0f0c678/top HTTP/1.1
244 
+
245 
+	**Example response**:
246 
+
247 
+	.. sourcecode:: http
248 
+
249 
+	   HTTP/1.1 200 OK
250 
+	   Content-Type: application/json
251 
+
252 
+	   {
253 
+		"Titles":[
254 
+			"USER",
255 
+			"PID",
256 
+			"%CPU",
257 
+			"%MEM",
258 
+			"VSZ",
259 
+			"RSS",
260 
+			"TTY",
261 
+			"STAT",
262 
+			"START",
263 
+			"TIME",
264 
+			"COMMAND"
265 
+			],
266 
+		"Processes":[
267 
+			["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
268 
+			["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
269 
+		]
270 
+	   }
271 
+
272 
+	:query ps_args: ps arguments to use (eg. aux)
273 
+	:statuscode 200: no error
274 
+	:statuscode 404: no such container
275 
+	:statuscode 500: server error
276 
+
277 
+
278 
+Inspect changes on a container's filesystem
279 
+*******************************************
280 
+
281 
+.. http:get:: /containers/(id)/changes
282 
+
283 
+	Inspect changes on container ``id`` 's filesystem
284 
+
285 
+	**Example request**:
286 
+
287 
+	.. sourcecode:: http
288 
+
289 
+	   GET /containers/4fa6e0f0c678/changes HTTP/1.1
290 
+
291 
+
292 
+	**Example response**:
293 
+
294 
+	.. sourcecode:: http
295 
+
296 
+	   HTTP/1.1 200 OK
297 
+	   Content-Type: application/json
298 
+
299 
+	   [
300 
+		{
301 
+			"Path":"/dev",
302 
+			"Kind":0
303 
+		},
304 
+		{
305 
+			"Path":"/dev/kmsg",
306 
+			"Kind":1
307 
+		},
308 
+		{
309 
+			"Path":"/test",
310 
+			"Kind":1
311 
+		}
312 
+	   ]
313 
+
314 
+	:statuscode 200: no error
315 
+	:statuscode 404: no such container
316 
+	:statuscode 500: server error
317 
+
318 
+
319 
+Export a container
320 
+******************
321 
+
322 
+.. http:get:: /containers/(id)/export
323 
+
324 
+	Export the contents of container ``id``
325 
+
326 
+	**Example request**:
327 
+
328 
+	.. sourcecode:: http
329 
+
330 
+	   GET /containers/4fa6e0f0c678/export HTTP/1.1
331 
+
332 
+
333 
+	**Example response**:
334 
+
335 
+	.. sourcecode:: http
336 
+
337 
+	   HTTP/1.1 200 OK
338 
+	   Content-Type: application/octet-stream
339 
+
340 
+	   {{ STREAM }}
341 
+
342 
+	:statuscode 200: no error
343 
+	:statuscode 404: no such container
344 
+	:statuscode 500: server error
345 
+
346 
+
347 
+Start a container
348 
+*****************
349 
+
350 
+.. http:post:: /containers/(id)/start
351 
+
352 
+        Start the container ``id``
353 
+
354 
+        **Example request**:
355 
+
356 
+        .. sourcecode:: http
357 
+
358 
+           POST /containers/(id)/start HTTP/1.1
359 
+           Content-Type: application/json
360 
+
361 
+           {
362 
+                "Binds":["/tmp:/tmp"],
363 
+                "LxcConf":{"lxc.utsname":"docker"}
364 
+           }
365 
+
366 
+        **Example response**:
367 
+
368 
+        .. sourcecode:: http
369 
+
370 
+           HTTP/1.1 204 No Content
371 
+           Content-Type: text/plain
372 
+
373 
+        :jsonparam hostConfig: the container's host configuration (optional)
374 
+        :statuscode 204: no error
375 
+        :statuscode 404: no such container
376 
+        :statuscode 500: server error
377 
+
378 
+
379 
+Stop a container
380 
+****************
381 
+
382 
+.. http:post:: /containers/(id)/stop
383 
+
384 
+	Stop the container ``id``
385 
+
386 
+	**Example request**:
387 
+
388 
+	.. sourcecode:: http
389 
+
390 
+	   POST /containers/e90e34656806/stop?t=5 HTTP/1.1
391 
+
392 
+	**Example response**:
393 
+
394 
+	.. sourcecode:: http
395 
+
396 
+	   HTTP/1.1 204 OK
397 
+
398 
+	:query t: number of seconds to wait before killing the container
399 
+	:statuscode 204: no error
400 
+	:statuscode 404: no such container
401 
+	:statuscode 500: server error
402 
+
403 
+
404 
+Restart a container
405 
+*******************
406 
+
407 
+.. http:post:: /containers/(id)/restart
408 
+
409 
+	Restart the container ``id``
410 
+
411 
+	**Example request**:
412 
+
413 
+	.. sourcecode:: http
414 
+
415 
+	   POST /containers/e90e34656806/restart?t=5 HTTP/1.1
416 
+
417 
+	**Example response**:
418 
+
419 
+	.. sourcecode:: http
420 
+
421 
+	   HTTP/1.1 204 OK
422 
+
423 
+	:query t: number of seconds to wait before killing the container
424 
+	:statuscode 204: no error
425 
+	:statuscode 404: no such container
426 
+	:statuscode 500: server error
427 
+
428 
+
429 
+Kill a container
430 
+****************
431 
+
432 
+.. http:post:: /containers/(id)/kill
433 
+
434 
+	Kill the container ``id``
435 
+
436 
+	**Example request**:
437 
+
438 
+	.. sourcecode:: http
439 
+
440 
+	   POST /containers/e90e34656806/kill HTTP/1.1
441 
+
442 
+	**Example response**:
443 
+
444 
+	.. sourcecode:: http
445 
+
446 
+	   HTTP/1.1 204 OK
447 
+
448 
+	:statuscode 204: no error
449 
+	:statuscode 404: no such container
450 
+	:statuscode 500: server error
451 
+
452 
+
453 
+Attach to a container
454 
+*********************
455 
+
456 
+.. http:post:: /containers/(id)/attach
457 
+
458 
+	Attach to the container ``id``
459 
+
460 
+	**Example request**:
461 
+
462 
+	.. sourcecode:: http
463 
+
464 
+	   POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
465 
+
466 
+	**Example response**:
467 
+
468 
+	.. sourcecode:: http
469 
+
470 
+	   HTTP/1.1 200 OK
471 
+	   Content-Type: application/vnd.docker.raw-stream
472 
+
473 
+	   {{ STREAM }}
474 
+
475 
+	:query logs: 1/True/true or 0/False/false, return logs. Default false
476 
+	:query stream: 1/True/true or 0/False/false, return stream. Default false
477 
+	:query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false
478 
+	:query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false
479 
+	:query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false
480 
+	:statuscode 200: no error
481 
+	:statuscode 400: bad parameter
482 
+	:statuscode 404: no such container
483 
+	:statuscode 500: server error
484 
+
485 
+	**Stream details**:
486 
+
487 
+	When using the TTY setting is enabled in
488 
+	:http:post:`/containers/create`, the stream is the raw data
489 
+	from the process PTY and client's stdin.  When the TTY is
490 
+	disabled, then the stream is multiplexed to separate stdout
491 
+	and stderr.
492 
+
493 
+	The format is a **Header** and a **Payload** (frame).
494 
+
495 
+	**HEADER**
496 
+
497 
+	The header will contain the information on which stream write
498 
+	the stream (stdout or stderr). It also contain the size of
499 
+	the associated frame encoded on the last 4 bytes (uint32).
500 
+
501 
+	It is encoded on the first 8 bytes like this::
502 
+
503 
+	    header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
504 
+
505 
+	``STREAM_TYPE`` can be:
506 
+
507 
+	- 0: stdin (will be writen on stdout)
508 
+	- 1: stdout
509 
+	- 2: stderr
510 
+
511 
+	``SIZE1, SIZE2, SIZE3, SIZE4`` are the 4 bytes of the uint32 size encoded as big endian.
512 
+
513 
+	**PAYLOAD**
514 
+
515 
+	The payload is the raw stream.
516 
+
517 
+	**IMPLEMENTATION**
518 
+
519 
+	The simplest way to implement the Attach protocol is the following:
520 
+
521 
+	1) Read 8 bytes
522 
+	2) chose stdout or stderr depending on the first byte
523 
+	3) Extract the frame size from the last 4 byets
524 
+	4) Read the extracted size and output it on the correct output
525 
+	5) Goto 1)
526 
+
527 
+
528 
+
529 
+Wait a container
530 
+****************
531 
+
532 
+.. http:post:: /containers/(id)/wait
533 
+
534 
+	Block until container ``id`` stops, then returns the exit code
535 
+
536 
+	**Example request**:
537 
+
538 
+	.. sourcecode:: http
539 
+
540 
+	   POST /containers/16253994b7c4/wait HTTP/1.1
541 
+
542 
+	**Example response**:
543 
+
544 
+	.. sourcecode:: http
545 
+
546 
+	   HTTP/1.1 200 OK
547 
+	   Content-Type: application/json
548 
+
549 
+	   {"StatusCode":0}
550 
+
551 
+	:statuscode 200: no error
552 
+	:statuscode 404: no such container
553 
+	:statuscode 500: server error
554 
+
555 
+
556 
+Remove a container
557 
+*******************
558 
+
559 
+.. http:delete:: /containers/(id)
560 
+
561 
+	Remove the container ``id`` from the filesystem
562 
+
563 
+	**Example request**:
564 
+
565 
+        .. sourcecode:: http
566 
+
567 
+           DELETE /containers/16253994b7c4?v=1 HTTP/1.1
568 
+
569 
+        **Example response**:
570 
+
571 
+        .. sourcecode:: http
572 
+
573 
+	   HTTP/1.1 204 OK
574 
+
575 
+	:query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false
576 
+        :statuscode 204: no error
577 
+	:statuscode 400: bad parameter
578 
+        :statuscode 404: no such container
579 
+        :statuscode 500: server error
580 
+
581 
+
582 
+Copy files or folders from a container
583 
+**************************************
584 
+
585 
+.. http:post:: /containers/(id)/copy
586 
+
587 
+	Copy files or folders of container ``id``
588 
+
589 
+	**Example request**:
590 
+
591 
+	.. sourcecode:: http
592 
+
593 
+	   POST /containers/4fa6e0f0c678/copy HTTP/1.1
594 
+	   Content-Type: application/json
595 
+
596 
+	   {
597 
+		"Resource":"test.txt"
598 
+	   }
599 
+
600 
+	**Example response**:
601 
+
602 
+	.. sourcecode:: http
603 
+
604 
+	   HTTP/1.1 200 OK
605 
+	   Content-Type: application/octet-stream
606 
+
607 
+	   {{ STREAM }}
608 
+
609 
+	:statuscode 200: no error
610 
+	:statuscode 404: no such container
611 
+	:statuscode 500: server error
612 
+
613 
+
614 
+2.2 Images
615 
+----------
616 
+
617 
+List Images
618 
+***********
619 
+
620 
+.. http:get:: /images/json
621 
+
622 
+	**Example request**:
623 
+
624 
+	.. sourcecode:: http
625 
+
626 
+	   GET /images/json?all=0 HTTP/1.1
627 
+
628 
+	**Example response**:
629 
+
630 
+	.. sourcecode:: http
631 
+
632 
+	   HTTP/1.1 200 OK
633 
+	   Content-Type: application/json
634 
+
635 
+	   [
636 
+	     {
637 
+	   	"RepoTag": [
638 
+	   	  "ubuntu:12.04",
639 
+	   	  "ubuntu:precise",
640 
+	   	  "ubuntu:latest"
641 
+	   	],
642 
+	   	"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
643 
+	   	"Created": 1365714795,
644 
+	   	"Size": 131506275,
645 
+	   	"VirtualSize": 131506275
646 
+	     },
647 
+	     {
648 
+	   	"RepoTag": [
649 
+	   	  "ubuntu:12.10",
650 
+	   	  "ubuntu:quantal"
651 
+	   	],
652 
+	   	"ParentId": "27cf784147099545",
653 
+	   	"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
654 
+	   	"Created": 1364102658,
655 
+	   	"Size": 24653,
656 
+	   	"VirtualSize": 180116135
657 
+	     }
658 
+	   ]
659 
+
660 
+
661 
+Create an image
662 
+***************
663 
+
664 
+.. http:post:: /images/create
665 
+
666 
+	Create an image, either by pull it from the registry or by importing it
667 
+
668 
+	**Example request**:
669 
+
670 
+        .. sourcecode:: http
671 
+
672 
+           POST /images/create?fromImage=base HTTP/1.1
673 
+
674 
+        **Example response**:
675 
+
676 
+        .. sourcecode:: http
677 
+
678 
+           HTTP/1.1 200 OK
679 
+	   Content-Type: application/json
680 
+
681 
+	   {"status":"Pulling..."}
682 
+	   {"status":"Pulling", "progress":"1/? (n/a)"}
683 
+	   {"error":"Invalid..."}
684 
+	   ...
685 
+
686 
+	When using this endpoint to pull an image from the registry,
687 
+	the ``X-Registry-Auth`` header can be used to include a
688 
+	base64-encoded AuthConfig object.
689 
+
690 
+        :query fromImage: name of the image to pull
691 
+	:query fromSrc: source to import, - means stdin
692 
+        :query repo: repository
693 
+	:query tag: tag
694 
+	:query registry: the registry to pull from
695 
+	:reqheader X-Registry-Auth: base64-encoded AuthConfig object
696 
+        :statuscode 200: no error
697 
+        :statuscode 500: server error
698 
+
699 
+
700 
+
701 
+Insert a file in an image
702 
+*************************
703 
+
704 
+.. http:post:: /images/(name)/insert
705 
+
706 
+	Insert a file from ``url`` in the image ``name`` at ``path``
707 
+
708 
+	**Example request**:
709 
+
710 
+        .. sourcecode:: http
711 
+
712 
+           POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
713 
+
714 
+	**Example response**:
715 
+
716 
+        .. sourcecode:: http
717 
+
718 
+           HTTP/1.1 200 OK
719 
+	   Content-Type: application/json
720 
+
721 
+	   {"status":"Inserting..."}
722 
+	   {"status":"Inserting", "progress":"1/? (n/a)"}
723 
+	   {"error":"Invalid..."}
724 
+	   ...
725 
+
726 
+	:statuscode 200: no error
727 
+        :statuscode 500: server error
728 
+
729 
+
730 
+Inspect an image
731 
+****************
732 
+
733 
+.. http:get:: /images/(name)/json
734 
+
735 
+	Return low-level information on the image ``name``
736 
+
737 
+	**Example request**:
738 
+
739 
+	.. sourcecode:: http
740 
+
741 
+	   GET /images/base/json HTTP/1.1
742 
+
743 
+	**Example response**:
744 
+
745 
+        .. sourcecode:: http
746 
+
747 
+           HTTP/1.1 200 OK
748 
+	   Content-Type: application/json
749 
+
750 
+	   {
751 
+		"id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
752 
+		"parent":"27cf784147099545",
753 
+		"created":"2013-03-23T22:24:18.818426-07:00",
754 
+		"container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
755 
+		"container_config":
756 
+			{
757 
+				"Hostname":"",
758 
+				"User":"",
759 
+				"Memory":0,
760 
+				"MemorySwap":0,
761 
+				"AttachStdin":false,
762 
+				"AttachStdout":false,
763 
+				"AttachStderr":false,
764 
+				"PortSpecs":null,
765 
+				"Tty":true,
766 
+				"OpenStdin":true,
767 
+				"StdinOnce":false,
768 
+				"Env":null,
769 
+				"Cmd": ["/bin/bash"]
770 
+				,"Dns":null,
771 
+				"Image":"base",
772 
+				"Volumes":null,
773 
+				"VolumesFrom":"",
774 
+				"WorkingDir":""
775 
+			},
776 
+		"Size": 6824592
777 
+	   }
778 
+
779 
+	:statuscode 200: no error
780 
+	:statuscode 404: no such image
781 
+        :statuscode 500: server error
782 
+
783 
+
784 
+Get the history of an image
785 
+***************************
786 
+
787 
+.. http:get:: /images/(name)/history
788 
+
789 
+        Return the history of the image ``name``
790 
+
791 
+        **Example request**:
792 
+
793 
+        .. sourcecode:: http
794 
+
795 
+           GET /images/base/history HTTP/1.1
796 
+
797 
+        **Example response**:
798 
+
799 
+        .. sourcecode:: http
800 
+
801 
+           HTTP/1.1 200 OK
802 
+	   Content-Type: application/json
803 
+
804 
+	   [
805 
+		{
806 
+			"Id":"b750fe79269d",
807 
+			"Created":1364102658,
808 
+			"CreatedBy":"/bin/bash"
809 
+		},
810 
+		{
811 
+			"Id":"27cf78414709",
812 
+			"Created":1364068391,
813 
+			"CreatedBy":""
814 
+		}
815 
+	   ]
816 
+
817 
+        :statuscode 200: no error
818 
+        :statuscode 404: no such image
819 
+        :statuscode 500: server error
820 
+
821 
+
822 
+Push an image on the registry
823 
+*****************************
824 
+
825 
+.. http:post:: /images/(name)/push
826 
+
827 
+   Push the image ``name`` on the registry
828 
+
829 
+   **Example request**:
830 
+
831 
+   .. sourcecode:: http
832 
+
833 
+      POST /images/test/push HTTP/1.1
834 
+
835 
+   **Example response**:
836 
+
837 
+   .. sourcecode:: http
838 
+
839 
+    HTTP/1.1 200 OK
840 
+    Content-Type: application/json
841 
+
842 
+    {"status":"Pushing..."}
843 
+    {"status":"Pushing", "progress":"1/? (n/a)"}
844 
+    {"error":"Invalid..."}
845 
+    ...
846 
+
847 
+   :query registry: the registry you wan to push, optional
848 
+   :reqheader X-Registry-Auth: include a base64-encoded AuthConfig object.
849 
+   :statuscode 200: no error
850 
+   :statuscode 404: no such image
851 
+   :statuscode 500: server error
852 
+
853 
+
854 
+Tag an image into a repository
855 
+******************************
856 
+
857 
+.. http:post:: /images/(name)/tag
858 
+
859 
+	Tag the image ``name`` into a repository
860 
+
861 
+        **Example request**:
862 
+
863 
+        .. sourcecode:: http
864 
+
865 
+	   POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
866 
+
867 
+	**Example response**:
868 
+
869 
+        .. sourcecode:: http
870 
+
871 
+           HTTP/1.1 200 OK
872 
+
873 
+	:query repo: The repository to tag in
874 
+	:query force: 1/True/true or 0/False/false, default false
875 
+	:statuscode 200: no error
876 
+	:statuscode 400: bad parameter
877 
+	:statuscode 404: no such image
878 
+	:statuscode 409: conflict
879 
+        :statuscode 500: server error
880 
+
881 
+
882 
+Remove an image
883 
+***************
884 
+
885 
+.. http:delete:: /images/(name)
886 
+
887 
+	Remove the image ``name`` from the filesystem
888 
+
889 
+	**Example request**:
890 
+
891 
+	.. sourcecode:: http
892 
+
893 
+	   DELETE /images/test HTTP/1.1
894 
+
895 
+	**Example response**:
896 
+
897 
+        .. sourcecode:: http
898 
+
899 
+	   HTTP/1.1 200 OK
900 
+	   Content-type: application/json
901 
+
902 
+	   [
903 
+	    {"Untagged":"3e2f21a89f"},
904 
+	    {"Deleted":"3e2f21a89f"},
905 
+	    {"Deleted":"53b4f83ac9"}
906 
+	   ]
907 
+
908 
+	:statuscode 200: no error
909 
+        :statuscode 404: no such image
910 
+	:statuscode 409: conflict
911 
+        :statuscode 500: server error
912 
+
913 
+
914 
+Search images
915 
+*************
916 
+
917 
+.. http:get:: /images/search
918 
+
919 
+	Search for an image in the docker index.
920 
+
921 
+	.. note::
922 
+
923 
+	   The response keys have changed from API v1.6 to reflect the JSON
924 
+	   sent by the registry server to the docker daemon's request.
925 
+
926 
+	**Example request**:
927 
+
928 
+        .. sourcecode:: http
929 
+
930 
+           GET /images/search?term=sshd HTTP/1.1
931 
+
932 
+	**Example response**:
933 
+
934 
+	.. sourcecode:: http
935 
+
936 
+	   HTTP/1.1 200 OK
937 
+	   Content-Type: application/json
938 
+
939 
+	   [
940 
+		   {
941 
+		       "description": "",
942 
+		       "is_official": false,
943 
+		       "is_trusted": false,
944 
+		       "name": "wma55/u1210sshd",
945 
+		       "star_count": 0
946 
+		   },
947 
+		   {
948 
+		       "description": "",
949 
+		       "is_official": false,
950 
+		       "is_trusted": false,
951 
+		       "name": "jdswinbank/sshd",
952 
+		       "star_count": 0
953 
+		   },
954 
+		   {
955 
+		       "description": "",
956 
+		       "is_official": false,
957 
+		       "is_trusted": false,
958 
+		       "name": "vgauthier/sshd",
959 
+		       "star_count": 0
960 
+		   }
961 
+	   ...
962 
+	   ]
963 
+
964 
+	:query term: term to search
965 
+	:statuscode 200: no error
966 
+	:statuscode 500: server error
967 
+
968 
+
969 
+2.3 Misc
970 
+--------
971 
+
972 
+Build an image from Dockerfile via stdin
973 
+****************************************
974 
+
975 
+.. http:post:: /build
976 
+
977 
+   Build an image from Dockerfile via stdin
978 
+
979 
+   **Example request**:
980 
+
981 
+   .. sourcecode:: http
982 
+
983 
+      POST /build HTTP/1.1
984 
+
985 
+      {{ STREAM }}
986 
+
987 
+   **Example response**:
988 
+
989 
+   .. sourcecode:: http
990 
+
991 
+      HTTP/1.1 200 OK
992 
+      Content-Type: application/json
993 
+
994 
+      {"status":"Step 1..."}
995 
+      {"status":"..."}
996 
+      {"error":"Error...", "errorDetail":{"code": 123, "message": "Error..."}}
997 
+
998 
+
999 
+   The stream must be a tar archive compressed with one of the
1000 
+   following algorithms: identity (no compression), gzip, bzip2,
1001 
+   xz.
1002 
+
1003 
+   The archive must include a file called ``Dockerfile`` at its
1004 
+   root. It may include any number of other files, which will be
1005 
+   accessible in the build context (See the :ref:`ADD build command
1006 
+   <dockerbuilder>`).
1007 
+
1008 
+   :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
1009 
+   :query q: suppress verbose build output
1010 
+   :query nocache: do not use the cache when building the image
1011 
+   :reqheader Content-type: should be set to ``"application/tar"``.
1012 
+   :statuscode 200: no error
1013 
+   :statuscode 500: server error
1014 
+
1015 
+
1016 
+
1017 
+Check auth configuration
1018 
+************************
1019 
+
1020 
+.. http:post:: /auth
1021 
+
1022 
+        Get the default username and email
1023 
+
1024 
+        **Example request**:
1025 
+
1026 
+        .. sourcecode:: http
1027 
+
1028 
+           POST /auth HTTP/1.1
1029 
+	   Content-Type: application/json
1030 
+
1031 
+	   {
1032 
+		"username":"hannibal",
1033 
+		"password:"xxxx",
1034 
+		"email":"hannibal@a-team.com",
1035 
+		"serveraddress":"https://index.docker.io/v1/"
1036 
+	   }
1037 
+
1038 
+        **Example response**:
1039 
+
1040 
+        .. sourcecode:: http
1041 
+
1042 
+           HTTP/1.1 200 OK
1043 
+
1044 
+        :statuscode 200: no error
1045 
+        :statuscode 204: no error
1046 
+        :statuscode 500: server error
1047 
+
1048 
+
1049 
+Display system-wide information
1050 
+*******************************
1051 
+
1052 
+.. http:get:: /info
1053 
+
1054 
+	Display system-wide information
1055 
+
1056 
+	**Example request**:
1057 
+
1058 
+        .. sourcecode:: http
1059 
+
1060 
+           GET /info HTTP/1.1
1061 
+
1062 
+        **Example response**:
1063 
+
1064 
+        .. sourcecode:: http
1065 
+
1066 
+           HTTP/1.1 200 OK
1067 
+	   Content-Type: application/json
1068 
+
1069 
+	   {
1070 
+		"Containers":11,
1071 
+		"Images":16,
1072 
+		"Debug":false,
1073 
+		"NFd": 11,
1074 
+		"NGoroutines":21,
1075 
+		"MemoryLimit":true,
1076 
+		"SwapLimit":false,
1077 
+		"IPv4Forwarding":true
1078 
+	   }
1079 
+
1080 
+        :statuscode 200: no error
1081 
+        :statuscode 500: server error
1082 
+
1083 
+
1084 
+Show the docker version information
1085 
+***********************************
1086 
+
1087 
+.. http:get:: /version
1088 
+
1089 
+	Show the docker version information
1090 
+
1091 
+	**Example request**:
1092 
+
1093 
+        .. sourcecode:: http
1094 
+
1095 
+           GET /version HTTP/1.1
1096 
+
1097 
+        **Example response**:
1098 
+
1099 
+        .. sourcecode:: http
1100 
+
1101 
+           HTTP/1.1 200 OK
1102 
+	   Content-Type: application/json
1103 
+
1104 
+	   {
1105 
+		"Version":"0.2.2",
1106 
+		"GitCommit":"5a2a5cc+CHANGES",
1107 
+		"GoVersion":"go1.0.3"
1108 
+	   }
1109 
+
1110 
+        :statuscode 200: no error
1111 
+	:statuscode 500: server error
1112 
+
1113 
+
1114 
+Create a new image from a container's changes
1115 
+*********************************************
1116 
+
1117 
+.. http:post:: /commit
1118 
+
1119 
+    Create a new image from a container's changes
1120 
+
1121 
+    **Example request**:
1122 
+
1123 
+    .. sourcecode:: http
1124 
+
1125 
+        POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
1126 
+
1127 
+    **Example response**:
1128 
+
1129 
+    .. sourcecode:: http
1130 
+
1131 
+        HTTP/1.1 201 OK
1132 
+	    Content-Type: application/vnd.docker.raw-stream
1133 
+
1134 
+        {"Id":"596069db4bf5"}
1135 
+
1136 
+    :query container: source container
1137 
+    :query repo: repository
1138 
+    :query tag: tag
1139 
+    :query m: commit message
1140 
+    :query author: author (eg. "John Hannibal Smith <hannibal@a-team.com>")
1141 
+    :query run: config automatically applied when the image is run. (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
1142 
+    :statuscode 201: no error
1143 
+    :statuscode 404: no such container
1144 
+    :statuscode 500: server error
1145 
+
1146 
+
1147 
+Monitor Docker's events
1148 
+***********************
1149 
+
1150 
+.. http:get:: /events
1151 
+
1152 
+	Get events from docker, either in real time via streaming, or via polling (using `since`)
1153 
+
1154 
+	**Example request**:
1155 
+
1156 
+	.. sourcecode:: http
1157 
+
1158 
+           POST /events?since=1374067924
1159 
+
1160 
+        **Example response**:
1161 
+
1162 
+        .. sourcecode:: http
1163 
+
1164 
+           HTTP/1.1 200 OK
1165 
+	   Content-Type: application/json
1166 
+
1167 
+	   {"status":"create","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
1168 
+	   {"status":"start","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
1169 
+	   {"status":"stop","id":"dfdf82bd3881","from":"base:latest","time":1374067966}
1170 
+	   {"status":"destroy","id":"dfdf82bd3881","from":"base:latest","time":1374067970}
1171 
+
1172 
+	:query since: timestamp used for polling
1173 
+        :statuscode 200: no error
1174 
+        :statuscode 500: server error
1175 
+
1176 
+Get a tarball containing all images and tags in a repository
1177 
+************************************************************
1178 
+
1179 
+.. http:get:: /images/(name)/get
1180 
+
1181 
+  Get a tarball containing all images and metadata for the repository specified by ``name``.
1182 
+
1183 
+  **Example request**
1184 
+
1185 
+  .. sourcecode:: http
1186 
+
1187 
+           GET /images/ubuntu/get
1188 
+
1189 
+       **Example response**:
1190 
+
1191 
+       .. sourcecode:: http
1192 
+
1193 
+          HTTP/1.1 200 OK
1194 
+    Content-Type: application/x-tar
1195 
+
1196 
+    Binary data stream
1197 
+        :statuscode 200: no error
1198 
+        :statuscode 500: server error
1199 
+
1200 
+Load a tarball with a set of images and tags into docker
1201 
+********************************************************
1202 
+
1203 
+.. http:post:: /images/load
1204 
+
1205 
+  Load a set of images and tags into the docker repository.
1206 
+
1207 
+  **Example request**
1208 
+
1209 
+  .. sourcecode:: http
1210 
+
1211 
+           POST /images/load
1212 
+
1213 
+         Tarball in body
1214 
+
1215 
+       **Example response**:
1216 
+
1217 
+       .. sourcecode:: http
1218 
+
1219 
+          HTTP/1.1 200 OK
1220 
+
1221 
+        :statuscode 200: no error
1222 
+        :statuscode 500: server error
1223 
+
1224 
+3. Going further
1225 
+================
1226 
+
1227 
+3.1 Inside 'docker run'
1228 
+-----------------------
1229 
+
1230 
+Here are the steps of 'docker run' :
1231 
+
1232 
+* Create the container
1233 
+* If the status code is 404, it means the image doesn't exists:
1234 
+        * Try to pull it
1235 
+        * Then retry to create the container
1236 
+* Start the container
1237 
+* If you are not in detached mode:
1238 
+        * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1
1239 
+* If in detached mode or only stdin is attached:
1240 
+	* Display the container's id
1241 
+
1242 
+
1243 
+3.2 Hijacking
1244 
+-------------
1245 
+
1246 
+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.
1247 
+
1248 
+3.3 CORS Requests
1249 
+-----------------
1250 
+
1251 
+To enable cross origin requests to the remote api add the flag "-api-enable-cors" when running docker in daemon mode.
1252 
+
1253 
+.. code-block:: bash
1254 
+
1255 
+   docker -d -H="192.168.1.9:4243" -api-enable-cors
1256 
+