docker_remote_api_v1.6.rst 25 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228
  1. :title: Remote API v1.6
  2. :description: API Documentation for Docker
  3. :keywords: API, Docker, rcli, REST, documentation
  4. :orphan:
  5. ======================
  6. Docker Remote API v1.6
  7. ======================
  8. .. contents:: Table of Contents
  9. 1. Brief introduction
  10. =====================
  11. - The Remote API has replaced rcli
  12. - The daemon listens on ``unix:///var/run/docker.sock``, but you can
  13. :ref:`bind_docker`.
  14. - The API tends to be REST, but for some complex commands, like
  15. ``attach`` or ``pull``, the HTTP connection is hijacked to transport
  16. ``stdout, stdin`` and ``stderr``
  17. 2. Endpoints
  18. ============
  19. 2.1 Containers
  20. --------------
  21. List containers
  22. ***************
  23. .. http:get:: /containers/json
  24. List containers
  25. **Example request**:
  26. .. sourcecode:: http
  27. GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
  28. **Example response**:
  29. .. sourcecode:: http
  30. HTTP/1.1 200 OK
  31. Content-Type: application/json
  32. [
  33. {
  34. "Id": "8dfafdbc3a40",
  35. "Image": "base:latest",
  36. "Command": "echo 1",
  37. "Created": 1367854155,
  38. "Status": "Exit 0",
  39. "Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
  40. "SizeRw":12288,
  41. "SizeRootFs":0
  42. },
  43. {
  44. "Id": "9cd87474be90",
  45. "Image": "base:latest",
  46. "Command": "echo 222222",
  47. "Created": 1367854155,
  48. "Status": "Exit 0",
  49. "Ports":[],
  50. "SizeRw":12288,
  51. "SizeRootFs":0
  52. },
  53. {
  54. "Id": "3176a2479c92",
  55. "Image": "base:latest",
  56. "Command": "echo 3333333333333333",
  57. "Created": 1367854154,
  58. "Status": "Exit 0",
  59. "Ports":[],
  60. "SizeRw":12288,
  61. "SizeRootFs":0
  62. },
  63. {
  64. "Id": "4cb07b47f9fb",
  65. "Image": "base:latest",
  66. "Command": "echo 444444444444444444444444444444444",
  67. "Created": 1367854152,
  68. "Status": "Exit 0",
  69. "Ports":[],
  70. "SizeRw":12288,
  71. "SizeRootFs":0
  72. }
  73. ]
  74. :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
  75. :query limit: Show ``limit`` last created containers, include non-running ones.
  76. :query since: Show only containers created since Id, include non-running ones.
  77. :query before: Show only containers created before Id, include non-running ones.
  78. :query size: 1/True/true or 0/False/false, Show the containers sizes
  79. :statuscode 200: no error
  80. :statuscode 400: bad parameter
  81. :statuscode 500: server error
  82. Create a container
  83. ******************
  84. .. http:post:: /containers/create
  85. Create a container
  86. **Example request**:
  87. .. sourcecode:: http
  88. POST /containers/create HTTP/1.1
  89. Content-Type: application/json
  90. {
  91. "Hostname":"",
  92. "User":"",
  93. "Memory":0,
  94. "MemorySwap":0,
  95. "AttachStdin":false,
  96. "AttachStdout":true,
  97. "AttachStderr":true,
  98. "PortSpecs":null,
  99. "Privileged": false,
  100. "Tty":false,
  101. "OpenStdin":false,
  102. "StdinOnce":false,
  103. "Env":null,
  104. "Cmd":[
  105. "date"
  106. ],
  107. "Dns":null,
  108. "Image":"base",
  109. "Volumes":{},
  110. "VolumesFrom":"",
  111. "WorkingDir":""
  112. }
  113. **Example response**:
  114. .. sourcecode:: http
  115. HTTP/1.1 201 OK
  116. Content-Type: application/json
  117. {
  118. "Id":"e90e34656806"
  119. "Warnings":[]
  120. }
  121. :jsonparam config: the container's configuration
  122. :query name: container name to use
  123. :statuscode 201: no error
  124. :statuscode 404: no such container
  125. :statuscode 406: impossible to attach (container not running)
  126. :statuscode 500: server error
  127. Inspect a container
  128. *******************
  129. .. http:get:: /containers/(id)/json
  130. Return low-level information on the container ``id``
  131. **Example request**:
  132. .. sourcecode:: http
  133. GET /containers/4fa6e0f0c678/json HTTP/1.1
  134. **Example response**:
  135. .. sourcecode:: http
  136. HTTP/1.1 200 OK
  137. Content-Type: application/json
  138. {
  139. "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
  140. "Created": "2013-05-07T14:51:42.041847+02:00",
  141. "Path": "date",
  142. "Args": [],
  143. "Config": {
  144. "Hostname": "4fa6e0f0c678",
  145. "User": "",
  146. "Memory": 0,
  147. "MemorySwap": 0,
  148. "AttachStdin": false,
  149. "AttachStdout": true,
  150. "AttachStderr": true,
  151. "PortSpecs": null,
  152. "Tty": false,
  153. "OpenStdin": false,
  154. "StdinOnce": false,
  155. "Env": null,
  156. "Cmd": [
  157. "date"
  158. ],
  159. "Dns": null,
  160. "Image": "base",
  161. "Volumes": {},
  162. "VolumesFrom": "",
  163. "WorkingDir":""
  164. },
  165. "State": {
  166. "Running": false,
  167. "Pid": 0,
  168. "ExitCode": 0,
  169. "StartedAt": "2013-05-07T14:51:42.087658+02:01360",
  170. "Ghost": false
  171. },
  172. "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  173. "NetworkSettings": {
  174. "IpAddress": "",
  175. "IpPrefixLen": 0,
  176. "Gateway": "",
  177. "Bridge": "",
  178. "PortMapping": null
  179. },
  180. "SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
  181. "ResolvConfPath": "/etc/resolv.conf",
  182. "Volumes": {}
  183. }
  184. :statuscode 200: no error
  185. :statuscode 404: no such container
  186. :statuscode 500: server error
  187. List processes running inside a container
  188. *****************************************
  189. .. http:get:: /containers/(id)/top
  190. List processes running inside the container ``id``
  191. **Example request**:
  192. .. sourcecode:: http
  193. GET /containers/4fa6e0f0c678/top HTTP/1.1
  194. **Example response**:
  195. .. sourcecode:: http
  196. HTTP/1.1 200 OK
  197. Content-Type: application/json
  198. {
  199. "Titles":[
  200. "USER",
  201. "PID",
  202. "%CPU",
  203. "%MEM",
  204. "VSZ",
  205. "RSS",
  206. "TTY",
  207. "STAT",
  208. "START",
  209. "TIME",
  210. "COMMAND"
  211. ],
  212. "Processes":[
  213. ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
  214. ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
  215. ]
  216. }
  217. :query ps_args: ps arguments to use (eg. aux)
  218. :statuscode 200: no error
  219. :statuscode 404: no such container
  220. :statuscode 500: server error
  221. Inspect changes on a container's filesystem
  222. *******************************************
  223. .. http:get:: /containers/(id)/changes
  224. Inspect changes on container ``id`` 's filesystem
  225. **Example request**:
  226. .. sourcecode:: http
  227. GET /containers/4fa6e0f0c678/changes HTTP/1.1
  228. **Example response**:
  229. .. sourcecode:: http
  230. HTTP/1.1 200 OK
  231. Content-Type: application/json
  232. [
  233. {
  234. "Path":"/dev",
  235. "Kind":0
  236. },
  237. {
  238. "Path":"/dev/kmsg",
  239. "Kind":1
  240. },
  241. {
  242. "Path":"/test",
  243. "Kind":1
  244. }
  245. ]
  246. :statuscode 200: no error
  247. :statuscode 404: no such container
  248. :statuscode 500: server error
  249. Export a container
  250. ******************
  251. .. http:get:: /containers/(id)/export
  252. Export the contents of container ``id``
  253. **Example request**:
  254. .. sourcecode:: http
  255. GET /containers/4fa6e0f0c678/export HTTP/1.1
  256. **Example response**:
  257. .. sourcecode:: http
  258. HTTP/1.1 200 OK
  259. Content-Type: application/octet-stream
  260. {{ STREAM }}
  261. :statuscode 200: no error
  262. :statuscode 404: no such container
  263. :statuscode 500: server error
  264. Start a container
  265. *****************
  266. .. http:post:: /containers/(id)/start
  267. Start the container ``id``
  268. **Example request**:
  269. .. sourcecode:: http
  270. POST /containers/(id)/start HTTP/1.1
  271. Content-Type: application/json
  272. {
  273. "Binds":["/tmp:/tmp"],
  274. "LxcConf":{"lxc.utsname":"docker"}
  275. }
  276. **Example response**:
  277. .. sourcecode:: http
  278. HTTP/1.1 204 No Content
  279. Content-Type: text/plain
  280. :jsonparam hostConfig: the container's host configuration (optional)
  281. :statuscode 204: no error
  282. :statuscode 404: no such container
  283. :statuscode 500: server error
  284. Stop a container
  285. ****************
  286. .. http:post:: /containers/(id)/stop
  287. Stop the container ``id``
  288. **Example request**:
  289. .. sourcecode:: http
  290. POST /containers/e90e34656806/stop?t=5 HTTP/1.1
  291. **Example response**:
  292. .. sourcecode:: http
  293. HTTP/1.1 204 OK
  294. :query t: number of seconds to wait before killing the container
  295. :statuscode 204: no error
  296. :statuscode 404: no such container
  297. :statuscode 500: server error
  298. Restart a container
  299. *******************
  300. .. http:post:: /containers/(id)/restart
  301. Restart the container ``id``
  302. **Example request**:
  303. .. sourcecode:: http
  304. POST /containers/e90e34656806/restart?t=5 HTTP/1.1
  305. **Example response**:
  306. .. sourcecode:: http
  307. HTTP/1.1 204 OK
  308. :query t: number of seconds to wait before killing the container
  309. :statuscode 204: no error
  310. :statuscode 404: no such container
  311. :statuscode 500: server error
  312. Kill a container
  313. ****************
  314. .. http:post:: /containers/(id)/kill
  315. Kill the container ``id``
  316. **Example request**:
  317. .. sourcecode:: http
  318. POST /containers/e90e34656806/kill HTTP/1.1
  319. **Example response**:
  320. .. sourcecode:: http
  321. HTTP/1.1 204 OK
  322. :query signal: Signal to send to the container (integer). When not set, SIGKILL is assumed and the call will waits for the container to exit.
  323. :statuscode 204: no error
  324. :statuscode 404: no such container
  325. :statuscode 500: server error
  326. Attach to a container
  327. *********************
  328. .. http:post:: /containers/(id)/attach
  329. Attach to the container ``id``
  330. **Example request**:
  331. .. sourcecode:: http
  332. POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
  333. **Example response**:
  334. .. sourcecode:: http
  335. HTTP/1.1 200 OK
  336. Content-Type: application/vnd.docker.raw-stream
  337. {{ STREAM }}
  338. :query logs: 1/True/true or 0/False/false, return logs. Default false
  339. :query stream: 1/True/true or 0/False/false, return stream. Default false
  340. :query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false
  341. :query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false
  342. :query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false
  343. :statuscode 200: no error
  344. :statuscode 400: bad parameter
  345. :statuscode 404: no such container
  346. :statuscode 500: server error
  347. **Stream details**:
  348. When using the TTY setting is enabled in
  349. :http:post:`/containers/create`, the stream is the raw data
  350. from the process PTY and client's stdin. When the TTY is
  351. disabled, then the stream is multiplexed to separate stdout
  352. and stderr.
  353. The format is a **Header** and a **Payload** (frame).
  354. **HEADER**
  355. The header will contain the information on which stream write
  356. the stream (stdout or stderr). It also contain the size of
  357. the associated frame encoded on the last 4 bytes (uint32).
  358. It is encoded on the first 8 bytes like this::
  359. header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
  360. ``STREAM_TYPE`` can be:
  361. - 0: stdin (will be writen on stdout)
  362. - 1: stdout
  363. - 2: stderr
  364. ``SIZE1, SIZE2, SIZE3, SIZE4`` are the 4 bytes of the uint32 size encoded as big endian.
  365. **PAYLOAD**
  366. The payload is the raw stream.
  367. **IMPLEMENTATION**
  368. The simplest way to implement the Attach protocol is the following:
  369. 1) Read 8 bytes
  370. 2) chose stdout or stderr depending on the first byte
  371. 3) Extract the frame size from the last 4 byets
  372. 4) Read the extracted size and output it on the correct output
  373. 5) Goto 1)
  374. Wait a container
  375. ****************
  376. .. http:post:: /containers/(id)/wait
  377. Block until container ``id`` stops, then returns the exit code
  378. **Example request**:
  379. .. sourcecode:: http
  380. POST /containers/16253994b7c4/wait HTTP/1.1
  381. **Example response**:
  382. .. sourcecode:: http
  383. HTTP/1.1 200 OK
  384. Content-Type: application/json
  385. {"StatusCode":0}
  386. :statuscode 200: no error
  387. :statuscode 404: no such container
  388. :statuscode 500: server error
  389. Remove a container
  390. *******************
  391. .. http:delete:: /containers/(id)
  392. Remove the container ``id`` from the filesystem
  393. **Example request**:
  394. .. sourcecode:: http
  395. DELETE /containers/16253994b7c4?v=1 HTTP/1.1
  396. **Example response**:
  397. .. sourcecode:: http
  398. HTTP/1.1 204 OK
  399. :query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false
  400. :statuscode 204: no error
  401. :statuscode 400: bad parameter
  402. :statuscode 404: no such container
  403. :statuscode 500: server error
  404. Copy files or folders from a container
  405. **************************************
  406. .. http:post:: /containers/(id)/copy
  407. Copy files or folders of container ``id``
  408. **Example request**:
  409. .. sourcecode:: http
  410. POST /containers/4fa6e0f0c678/copy HTTP/1.1
  411. Content-Type: application/json
  412. {
  413. "Resource":"test.txt"
  414. }
  415. **Example response**:
  416. .. sourcecode:: http
  417. HTTP/1.1 200 OK
  418. Content-Type: application/octet-stream
  419. {{ STREAM }}
  420. :statuscode 200: no error
  421. :statuscode 404: no such container
  422. :statuscode 500: server error
  423. 2.2 Images
  424. ----------
  425. List Images
  426. ***********
  427. .. http:get:: /images/(format)
  428. List images ``format`` could be json or viz (json default)
  429. **Example request**:
  430. .. sourcecode:: http
  431. GET /images/json?all=0 HTTP/1.1
  432. **Example response**:
  433. .. sourcecode:: http
  434. HTTP/1.1 200 OK
  435. Content-Type: application/json
  436. [
  437. {
  438. "Repository":"base",
  439. "Tag":"ubuntu-12.10",
  440. "Id":"b750fe79269d",
  441. "Created":1364102658,
  442. "Size":24653,
  443. "VirtualSize":180116135
  444. },
  445. {
  446. "Repository":"base",
  447. "Tag":"ubuntu-quantal",
  448. "Id":"b750fe79269d",
  449. "Created":1364102658,
  450. "Size":24653,
  451. "VirtualSize":180116135
  452. }
  453. ]
  454. **Example request**:
  455. .. sourcecode:: http
  456. GET /images/viz HTTP/1.1
  457. **Example response**:
  458. .. sourcecode:: http
  459. HTTP/1.1 200 OK
  460. Content-Type: text/plain
  461. digraph docker {
  462. "d82cbacda43a" -> "074be284591f"
  463. "1496068ca813" -> "08306dc45919"
  464. "08306dc45919" -> "0e7893146ac2"
  465. "b750fe79269d" -> "1496068ca813"
  466. base -> "27cf78414709" [style=invis]
  467. "f71189fff3de" -> "9a33b36209ed"
  468. "27cf78414709" -> "b750fe79269d"
  469. "0e7893146ac2" -> "d6434d954665"
  470. "d6434d954665" -> "d82cbacda43a"
  471. base -> "e9aa60c60128" [style=invis]
  472. "074be284591f" -> "f71189fff3de"
  473. "b750fe79269d" [label="b750fe79269d\nbase",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  474. "e9aa60c60128" [label="e9aa60c60128\nbase2",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  475. "9a33b36209ed" [label="9a33b36209ed\ntest",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  476. base [style=invisible]
  477. }
  478. :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
  479. :statuscode 200: no error
  480. :statuscode 400: bad parameter
  481. :statuscode 500: server error
  482. Create an image
  483. ***************
  484. .. http:post:: /images/create
  485. Create an image, either by pull it from the registry or by importing it
  486. **Example request**:
  487. .. sourcecode:: http
  488. POST /images/create?fromImage=base HTTP/1.1
  489. **Example response**:
  490. .. sourcecode:: http
  491. HTTP/1.1 200 OK
  492. Content-Type: application/json
  493. {"status":"Pulling..."}
  494. {"status":"Pulling", "progress":"1/? (n/a)"}
  495. {"error":"Invalid..."}
  496. ...
  497. When using this endpoint to pull an image from the registry,
  498. the ``X-Registry-Auth`` header can be used to include a
  499. base64-encoded AuthConfig object.
  500. :query fromImage: name of the image to pull
  501. :query fromSrc: source to import, - means stdin
  502. :query repo: repository
  503. :query tag: tag
  504. :query registry: the registry to pull from
  505. :statuscode 200: no error
  506. :statuscode 500: server error
  507. Insert a file in an image
  508. *************************
  509. .. http:post:: /images/(name)/insert
  510. Insert a file from ``url`` in the image ``name`` at ``path``
  511. **Example request**:
  512. .. sourcecode:: http
  513. POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
  514. **Example response**:
  515. .. sourcecode:: http
  516. HTTP/1.1 200 OK
  517. Content-Type: application/json
  518. {"status":"Inserting..."}
  519. {"status":"Inserting", "progress":"1/? (n/a)"}
  520. {"error":"Invalid..."}
  521. ...
  522. :statuscode 200: no error
  523. :statuscode 500: server error
  524. Inspect an image
  525. ****************
  526. .. http:get:: /images/(name)/json
  527. Return low-level information on the image ``name``
  528. **Example request**:
  529. .. sourcecode:: http
  530. GET /images/base/json HTTP/1.1
  531. **Example response**:
  532. .. sourcecode:: http
  533. HTTP/1.1 200 OK
  534. Content-Type: application/json
  535. {
  536. "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  537. "parent":"27cf784147099545",
  538. "created":"2013-03-23T22:24:18.818426-07:00",
  539. "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
  540. "container_config":
  541. {
  542. "Hostname":"",
  543. "User":"",
  544. "Memory":0,
  545. "MemorySwap":0,
  546. "AttachStdin":false,
  547. "AttachStdout":false,
  548. "AttachStderr":false,
  549. "PortSpecs":null,
  550. "Tty":true,
  551. "OpenStdin":true,
  552. "StdinOnce":false,
  553. "Env":null,
  554. "Cmd": ["/bin/bash"]
  555. ,"Dns":null,
  556. "Image":"base",
  557. "Volumes":null,
  558. "VolumesFrom":"",
  559. "WorkingDir":""
  560. },
  561. "Size": 6824592
  562. }
  563. :statuscode 200: no error
  564. :statuscode 404: no such image
  565. :statuscode 500: server error
  566. Get the history of an image
  567. ***************************
  568. .. http:get:: /images/(name)/history
  569. Return the history of the image ``name``
  570. **Example request**:
  571. .. sourcecode:: http
  572. GET /images/base/history HTTP/1.1
  573. **Example response**:
  574. .. sourcecode:: http
  575. HTTP/1.1 200 OK
  576. Content-Type: application/json
  577. [
  578. {
  579. "Id":"b750fe79269d",
  580. "Created":1364102658,
  581. "CreatedBy":"/bin/bash"
  582. },
  583. {
  584. "Id":"27cf78414709",
  585. "Created":1364068391,
  586. "CreatedBy":""
  587. }
  588. ]
  589. :statuscode 200: no error
  590. :statuscode 404: no such image
  591. :statuscode 500: server error
  592. Push an image on the registry
  593. *****************************
  594. .. http:post:: /images/(name)/push
  595. Push the image ``name`` on the registry
  596. **Example request**:
  597. .. sourcecode:: http
  598. POST /images/test/push HTTP/1.1
  599. **Example response**:
  600. .. sourcecode:: http
  601. HTTP/1.1 200 OK
  602. Content-Type: application/json
  603. {"status":"Pushing..."}
  604. {"status":"Pushing", "progress":"1/? (n/a)"}
  605. {"error":"Invalid..."}
  606. ...
  607. The ``X-Registry-Auth`` header can be used to include a
  608. base64-encoded AuthConfig object.
  609. :query registry: the registry you wan to push, optional
  610. :statuscode 200: no error
  611. :statuscode 404: no such image
  612. :statuscode 500: server error
  613. Tag an image into a repository
  614. ******************************
  615. .. http:post:: /images/(name)/tag
  616. Tag the image ``name`` into a repository
  617. **Example request**:
  618. .. sourcecode:: http
  619. POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
  620. **Example response**:
  621. .. sourcecode:: http
  622. HTTP/1.1 200 OK
  623. :query repo: The repository to tag in
  624. :query force: 1/True/true or 0/False/false, default false
  625. :statuscode 200: no error
  626. :statuscode 400: bad parameter
  627. :statuscode 404: no such image
  628. :statuscode 409: conflict
  629. :statuscode 500: server error
  630. Remove an image
  631. ***************
  632. .. http:delete:: /images/(name)
  633. Remove the image ``name`` from the filesystem
  634. **Example request**:
  635. .. sourcecode:: http
  636. DELETE /images/test HTTP/1.1
  637. **Example response**:
  638. .. sourcecode:: http
  639. HTTP/1.1 200 OK
  640. Content-type: application/json
  641. [
  642. {"Untagged":"3e2f21a89f"},
  643. {"Deleted":"3e2f21a89f"},
  644. {"Deleted":"53b4f83ac9"}
  645. ]
  646. :statuscode 200: no error
  647. :statuscode 404: no such image
  648. :statuscode 409: conflict
  649. :statuscode 500: server error
  650. Search images
  651. *************
  652. .. http:get:: /images/search
  653. Search for an image in the docker index
  654. **Example request**:
  655. .. sourcecode:: http
  656. GET /images/search?term=sshd HTTP/1.1
  657. **Example response**:
  658. .. sourcecode:: http
  659. HTTP/1.1 200 OK
  660. Content-Type: application/json
  661. [
  662. {
  663. "Name":"cespare/sshd",
  664. "Description":""
  665. },
  666. {
  667. "Name":"johnfuller/sshd",
  668. "Description":""
  669. },
  670. {
  671. "Name":"dhrp/mongodb-sshd",
  672. "Description":""
  673. }
  674. ]
  675. :query term: term to search
  676. :statuscode 200: no error
  677. :statuscode 500: server error
  678. 2.3 Misc
  679. --------
  680. Build an image from Dockerfile via stdin
  681. ****************************************
  682. .. http:post:: /build
  683. Build an image from Dockerfile via stdin
  684. **Example request**:
  685. .. sourcecode:: http
  686. POST /build HTTP/1.1
  687. {{ STREAM }}
  688. **Example response**:
  689. .. sourcecode:: http
  690. HTTP/1.1 200 OK
  691. {{ STREAM }}
  692. The stream must be a tar archive compressed with one of the following algorithms:
  693. identity (no compression), gzip, bzip2, xz. The archive must include a file called
  694. `Dockerfile` at its root. It may include any number of other files, which will be
  695. accessible in the build context (See the ADD build command).
  696. The Content-type header should be set to "application/tar".
  697. :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
  698. :query q: suppress verbose build output
  699. :query nocache: do not use the cache when building the image
  700. :statuscode 200: no error
  701. :statuscode 500: server error
  702. Check auth configuration
  703. ************************
  704. .. http:post:: /auth
  705. Get the default username and email
  706. **Example request**:
  707. .. sourcecode:: http
  708. POST /auth HTTP/1.1
  709. Content-Type: application/json
  710. {
  711. "username":"hannibal",
  712. "password:"xxxx",
  713. "email":"hannibal@a-team.com",
  714. "serveraddress":"https://index.docker.io/v1/"
  715. }
  716. **Example response**:
  717. .. sourcecode:: http
  718. HTTP/1.1 200 OK
  719. :statuscode 200: no error
  720. :statuscode 204: no error
  721. :statuscode 500: server error
  722. Display system-wide information
  723. *******************************
  724. .. http:get:: /info
  725. Display system-wide information
  726. **Example request**:
  727. .. sourcecode:: http
  728. GET /info HTTP/1.1
  729. **Example response**:
  730. .. sourcecode:: http
  731. HTTP/1.1 200 OK
  732. Content-Type: application/json
  733. {
  734. "Containers":11,
  735. "Images":16,
  736. "Debug":false,
  737. "NFd": 11,
  738. "NGoroutines":21,
  739. "MemoryLimit":true,
  740. "SwapLimit":false,
  741. "IPv4Forwarding":true
  742. }
  743. :statuscode 200: no error
  744. :statuscode 500: server error
  745. Show the docker version information
  746. ***********************************
  747. .. http:get:: /version
  748. Show the docker version information
  749. **Example request**:
  750. .. sourcecode:: http
  751. GET /version HTTP/1.1
  752. **Example response**:
  753. .. sourcecode:: http
  754. HTTP/1.1 200 OK
  755. Content-Type: application/json
  756. {
  757. "Version":"0.2.2",
  758. "GitCommit":"5a2a5cc+CHANGES",
  759. "GoVersion":"go1.0.3"
  760. }
  761. :statuscode 200: no error
  762. :statuscode 500: server error
  763. Create a new image from a container's changes
  764. *********************************************
  765. .. http:post:: /commit
  766. Create a new image from a container's changes
  767. **Example request**:
  768. .. sourcecode:: http
  769. POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
  770. Content-Type: application/json
  771. {
  772. "Cmd": ["cat", "/world"],
  773. "PortSpecs":["22"]
  774. }
  775. **Example response**:
  776. .. sourcecode:: http
  777. HTTP/1.1 201 OK
  778. Content-Type: application/vnd.docker.raw-stream
  779. {"Id":"596069db4bf5"}
  780. :query container: source container
  781. :query repo: repository
  782. :query tag: tag
  783. :query m: commit message
  784. :query author: author (eg. "John Hannibal Smith <hannibal@a-team.com>")
  785. :statuscode 201: no error
  786. :statuscode 404: no such container
  787. :statuscode 500: server error
  788. Monitor Docker's events
  789. ***********************
  790. .. http:get:: /events
  791. Get events from docker, either in real time via streaming, or via polling (using `since`)
  792. **Example request**:
  793. .. sourcecode:: http
  794. POST /events?since=1374067924
  795. **Example response**:
  796. .. sourcecode:: http
  797. HTTP/1.1 200 OK
  798. Content-Type: application/json
  799. {"status":"create","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
  800. {"status":"start","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
  801. {"status":"stop","id":"dfdf82bd3881","from":"base:latest","time":1374067966}
  802. {"status":"destroy","id":"dfdf82bd3881","from":"base:latest","time":1374067970}
  803. :query since: timestamp used for polling
  804. :statuscode 200: no error
  805. :statuscode 500: server error
  806. 3. Going further
  807. ================
  808. 3.1 Inside 'docker run'
  809. -----------------------
  810. Here are the steps of 'docker run' :
  811. * Create the container
  812. * If the status code is 404, it means the image doesn't exists:
  813. * Try to pull it
  814. * Then retry to create the container
  815. * Start the container
  816. * If you are not in detached mode:
  817. * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1
  818. * If in detached mode or only stdin is attached:
  819. * Display the container's id
  820. 3.2 Hijacking
  821. -------------
  822. 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.
  823. 3.3 CORS Requests
  824. -----------------
  825. To enable cross origin requests to the remote api add the flag "-api-enable-cors" when running docker in daemon mode.
  826. .. code-block:: bash
  827. docker -d -H="192.168.1.9:4243" -api-enable-cors