github.com/netbrain/docker@v1.9.0-rc2/docs/reference/api/docker_remote_api_v1.14.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Remote API v1.14" 4 description = "API Documentation for Docker" 5 keywords = ["API, Docker, rcli, REST, documentation"] 6 [menu.main] 7 parent = "smn_remoteapi" 8 weight = 7 9 +++ 10 <![end-metadata]--> 11 12 # Docker Remote API v1.14 13 14 ## 1. Brief introduction 15 16 - The Remote API has replaced `rcli`. 17 - The daemon listens on `unix:///var/run/docker.sock` but you can 18 [Bind Docker to another host/port or a Unix socket](../../articles/basics.md#bind-docker-to-another-hostport-or-a-unix-socket). 19 - The API tends to be REST, but for some complex commands, like `attach` 20 or `pull`, the HTTP connection is hijacked to transport `STDOUT`, 21 `STDIN` and `STDERR`. 22 23 # 2. Endpoints 24 25 ## 2.1 Containers 26 27 ### List containers 28 29 `GET /containers/json` 30 31 List containers 32 33 **Example request**: 34 35 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 36 37 **Example response**: 38 39 HTTP/1.1 200 OK 40 Content-Type: application/json 41 42 [ 43 { 44 "Id": "8dfafdbc3a40", 45 "Image": "ubuntu:latest", 46 "Command": "echo 1", 47 "Created": 1367854155, 48 "Status": "Exit 0", 49 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 50 "SizeRw": 12288, 51 "SizeRootFs": 0 52 }, 53 { 54 "Id": "9cd87474be90", 55 "Image": "ubuntu:latest", 56 "Command": "echo 222222", 57 "Created": 1367854155, 58 "Status": "Exit 0", 59 "Ports": [], 60 "SizeRw": 12288, 61 "SizeRootFs": 0 62 }, 63 { 64 "Id": "3176a2479c92", 65 "Image": "ubuntu:latest", 66 "Command": "echo 3333333333333333", 67 "Created": 1367854154, 68 "Status": "Exit 0", 69 "Ports":[], 70 "SizeRw":12288, 71 "SizeRootFs":0 72 }, 73 { 74 "Id": "4cb07b47f9fb", 75 "Image": "ubuntu:latest", 76 "Command": "echo 444444444444444444444444444444444", 77 "Created": 1367854152, 78 "Status": "Exit 0", 79 "Ports": [], 80 "SizeRw": 12288, 81 "SizeRootFs": 0 82 } 83 ] 84 85 Query Parameters: 86 87 - **all** – 1/True/true or 0/False/false, Show all containers. 88 Only running containers are shown by default (i.e., this defaults to false) 89 - **limit** – Show `limit` last created containers, include non-running ones. 90 - **since** – Show only containers created since Id, include non-running ones. 91 - **before** – Show only containers created before Id, include non-running ones. 92 - **size** – 1/True/true or 0/False/false, Show the containers sizes 93 - **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: 94 - exited=<int> -- containers with exit code of <int> 95 - status=(restarting|running|paused|exited) 96 97 Status Codes: 98 99 - **200** – no error 100 - **400** – bad parameter 101 - **500** – server error 102 103 ### Create a container 104 105 `POST /containers/create` 106 107 Create a container 108 109 **Example request**: 110 111 POST /containers/create HTTP/1.1 112 Content-Type: application/json 113 114 { 115 "Hostname":"", 116 "Domainname": "", 117 "User":"", 118 "Memory":0, 119 "MemorySwap":0, 120 "CpuShares": 512, 121 "Cpuset": "0,1", 122 "AttachStdin":false, 123 "AttachStdout":true, 124 "AttachStderr":true, 125 "PortSpecs":null, 126 "Tty":false, 127 "OpenStdin":false, 128 "StdinOnce":false, 129 "Env":null, 130 "Cmd":[ 131 "date" 132 ], 133 "Image":"ubuntu", 134 "Volumes":{ 135 "/tmp": {} 136 }, 137 "WorkingDir":"", 138 "NetworkDisabled": false, 139 "ExposedPorts":{ 140 "22/tcp": {} 141 }, 142 "RestartPolicy": { "Name": "always" } 143 } 144 145 **Example response**: 146 147 HTTP/1.1 201 Created 148 Content-Type: application/json 149 150 { 151 "Id":"e90e34656806" 152 "Warnings":[] 153 } 154 155 Json Parameters: 156 157 - **RestartPolicy** – The behavior to apply when the container exits. The 158 value is an object with a `Name` property of either `"always"` to 159 always restart or `"on-failure"` to restart only when the container 160 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 161 controls the number of times to retry before giving up. 162 The default is not to restart. (optional) 163 An ever increasing delay (double the previous delay, starting at 100mS) 164 is added before each restart to prevent flooding the server. 165 - **config** – the container's configuration 166 167 Query Parameters: 168 169 - **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. 170 171 Status Codes: 172 173 - **201** – no error 174 - **404** – no such container 175 - **406** – impossible to attach (container not running) 176 - **500** – server error 177 178 ### Inspect a container 179 180 `GET /containers/(id)/json` 181 182 Return low-level information on the container `id` 183 184 185 **Example request**: 186 187 GET /containers/4fa6e0f0c678/json HTTP/1.1 188 189 **Example response**: 190 191 HTTP/1.1 200 OK 192 Content-Type: application/json 193 194 { 195 "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", 196 "Created": "2013-05-07T14:51:42.041847+02:00", 197 "Path": "date", 198 "Args": [], 199 "Config": { 200 "Hostname": "4fa6e0f0c678", 201 "User": "", 202 "Memory": 0, 203 "MemorySwap": 0, 204 "AttachStdin": false, 205 "AttachStdout": true, 206 "AttachStderr": true, 207 "PortSpecs": null, 208 "Tty": false, 209 "OpenStdin": false, 210 "StdinOnce": false, 211 "Env": null, 212 "Cmd": [ 213 "date" 214 ], 215 "Dns": null, 216 "Image": "ubuntu", 217 "Volumes": {}, 218 "VolumesFrom": "", 219 "WorkingDir": "" 220 }, 221 "State": { 222 "Running": false, 223 "Pid": 0, 224 "ExitCode": 0, 225 "StartedAt": "2013-05-07T14:51:42.087658+02:01360", 226 "Ghost": false 227 }, 228 "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 229 "NetworkSettings": { 230 "IpAddress": "", 231 "IpPrefixLen": 0, 232 "Gateway": "", 233 "Bridge": "", 234 "PortMapping": null 235 }, 236 "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", 237 "ResolvConfPath": "/etc/resolv.conf", 238 "Volumes": {}, 239 "HostConfig": { 240 "Binds": null, 241 "ContainerIDFile": "", 242 "LxcConf": [], 243 "Privileged": false, 244 "PortBindings": { 245 "80/tcp": [ 246 { 247 "HostIp": "0.0.0.0", 248 "HostPort": "49153" 249 } 250 ] 251 }, 252 "Links": ["/name:alias"], 253 "PublishAllPorts": false, 254 "CapAdd": ["NET_ADMIN"], 255 "CapDrop": ["MKNOD"] 256 } 257 } 258 259 Status Codes: 260 261 - **200** – no error 262 - **404** – no such container 263 - **500** – server error 264 265 ### List processes running inside a container 266 267 `GET /containers/(id)/top` 268 269 List processes running inside the container `id` 270 271 **Example request**: 272 273 GET /containers/4fa6e0f0c678/top HTTP/1.1 274 275 **Example response**: 276 277 HTTP/1.1 200 OK 278 Content-Type: application/json 279 280 { 281 "Titles": [ 282 "USER", 283 "PID", 284 "%CPU", 285 "%MEM", 286 "VSZ", 287 "RSS", 288 "TTY", 289 "STAT", 290 "START", 291 "TIME", 292 "COMMAND" 293 ], 294 "Processes": [ 295 ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], 296 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] 297 ] 298 } 299 300 Query Parameters: 301 302 - **ps_args** – ps arguments to use (e.g., aux) 303 304 Status Codes: 305 306 - **200** – no error 307 - **404** – no such container 308 - **500** – server error 309 310 ### Get container logs 311 312 `GET /containers/(id)/logs` 313 314 Get stdout and stderr logs from the container ``id`` 315 316 **Example request**: 317 318 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 319 320 **Example response**: 321 322 HTTP/1.1 200 OK 323 Content-Type: application/vnd.docker.raw-stream 324 325 {{ STREAM }} 326 327 Query Parameters: 328 329 - **follow** – 1/True/true or 0/False/false, return stream. Default false 330 - **stdout** – 1/True/true or 0/False/false, show stdout log. Default false 331 - **stderr** – 1/True/true or 0/False/false, show stderr log. Default false 332 - **timestamps** – 1/True/true or 0/False/false, print timestamps for every 333 log line. Default false 334 - **tail** – Output specified number of lines at the end of logs: `all` or 335 `<number>`. Default all 336 337 Status Codes: 338 339 - **200** – no error 340 - **404** – no such container 341 - **500** – server error 342 343 ### Inspect changes on a container's filesystem 344 345 `GET /containers/(id)/changes` 346 347 Inspect changes on container `id`'s filesystem 348 349 **Example request**: 350 351 GET /containers/4fa6e0f0c678/changes HTTP/1.1 352 353 **Example response**: 354 355 HTTP/1.1 200 OK 356 Content-Type: application/json 357 358 [ 359 { 360 "Path": "/dev", 361 "Kind": 0 362 }, 363 { 364 "Path": "/dev/kmsg", 365 "Kind": 1 366 }, 367 { 368 "Path": "/test", 369 "Kind": 1 370 } 371 ] 372 373 Status Codes: 374 375 - **200** – no error 376 - **404** – no such container 377 - **500** – server error 378 379 ### Export a container 380 381 `GET /containers/(id)/export` 382 383 Export the contents of container `id` 384 385 **Example request**: 386 387 GET /containers/4fa6e0f0c678/export HTTP/1.1 388 389 **Example response**: 390 391 HTTP/1.1 200 OK 392 Content-Type: application/octet-stream 393 394 {{ TAR STREAM }} 395 396 Status Codes: 397 398 - **200** – no error 399 - **404** – no such container 400 - **500** – server error 401 402 ### Start a container 403 404 `POST /containers/(id)/start` 405 406 Start the container `id` 407 408 **Example request**: 409 410 POST /containers/(id)/start HTTP/1.1 411 Content-Type: application/json 412 413 { 414 "Binds":["/tmp:/tmp"], 415 "Links":["redis3:redis"], 416 "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], 417 "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, 418 "PublishAllPorts":false, 419 "Privileged":false, 420 "Dns": ["8.8.8.8"], 421 "VolumesFrom": ["parent", "other:ro"], 422 "CapAdd": ["NET_ADMIN"], 423 "CapDrop": ["MKNOD"] 424 } 425 426 **Example response**: 427 428 HTTP/1.1 204 No Content 429 430 Json Parameters: 431 432 - **hostConfig** – the container's host configuration (optional) 433 434 Status Codes: 435 436 - **204** – no error 437 - **304** – container already started 438 - **404** – no such container 439 - **500** – server error 440 441 ### Stop a container 442 443 `POST /containers/(id)/stop` 444 445 Stop the container `id` 446 447 **Example request**: 448 449 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 450 451 **Example response**: 452 453 HTTP/1.1 204 No Content 454 455 Query Parameters: 456 457 - **t** – number of seconds to wait before killing the container 458 459 Status Codes: 460 461 - **204** – no error 462 - **304** – container already stopped 463 - **404** – no such container 464 - **500** – server error 465 466 ### Restart a container 467 468 `POST /containers/(id)/restart` 469 470 Restart the container `id` 471 472 **Example request**: 473 474 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 475 476 **Example response**: 477 478 HTTP/1.1 204 No Content 479 480 Query Parameters: 481 482 - **t** – number of seconds to wait before killing the container 483 484 Status Codes: 485 486 - **204** – no error 487 - **404** – no such container 488 - **500** – server error 489 490 ### Kill a container 491 492 `POST /containers/(id)/kill` 493 494 Kill the container `id` 495 496 **Example request**: 497 498 POST /containers/e90e34656806/kill HTTP/1.1 499 500 **Example response**: 501 502 HTTP/1.1 204 No Content 503 504 Query Parameters 505 506 - **signal** - Signal to send to the container: integer or string like "SIGINT". 507 When not set, SIGKILL is assumed and the call will wait for the container to exit. 508 509 Status Codes: 510 511 - **204** – no error 512 - **404** – no such container 513 - **500** – server error 514 515 ### Pause a container 516 517 `POST /containers/(id)/pause` 518 519 Pause the container `id` 520 521 **Example request**: 522 523 POST /containers/e90e34656806/pause HTTP/1.1 524 525 **Example response**: 526 527 HTTP/1.1 204 No Content 528 529 Status Codes: 530 531 - **204** – no error 532 - **404** – no such container 533 - **500** – server error 534 535 ### Unpause a container 536 537 `POST /containers/(id)/unpause` 538 539 Unpause the container `id` 540 541 **Example request**: 542 543 POST /containers/e90e34656806/unpause HTTP/1.1 544 545 **Example response**: 546 547 HTTP/1.1 204 No Content 548 549 Status Codes: 550 551 - **204** – no error 552 - **404** – no such container 553 - **500** – server error 554 555 ### Attach to a container 556 557 `POST /containers/(id)/attach` 558 559 Attach to the container `id` 560 561 **Example request**: 562 563 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 564 565 **Example response**: 566 567 HTTP/1.1 200 OK 568 Content-Type: application/vnd.docker.raw-stream 569 570 {{ STREAM }} 571 572 Query Parameters: 573 574 - **logs** – 1/True/true or 0/False/false, return logs. Default false 575 - **stream** – 1/True/true or 0/False/false, return stream. Default false 576 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. 577 Default false 578 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 579 stdout log, if stream=true, attach to stdout. Default false 580 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 581 stderr log, if stream=true, attach to stderr. Default false 582 583 Status Codes: 584 585 - **200** – no error 586 - **400** – bad parameter 587 - **404** – no such container 588 - **500** – server error 589 590 **Stream details**: 591 592 When using the TTY setting is enabled in 593 [`POST /containers/create`](#create-a-container), 594 the stream is the raw data from the process PTY and client's stdin. 595 When the TTY is disabled, then the stream is multiplexed to separate 596 stdout and stderr. 597 598 The format is a **Header** and a **Payload** (frame). 599 600 **HEADER** 601 602 The header will contain the information on which stream write the 603 stream (stdout or stderr). It also contain the size of the 604 associated frame encoded on the last 4 bytes (uint32). 605 606 It is encoded on the first 8 bytes like this: 607 608 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 609 610 `STREAM_TYPE` can be: 611 612 - 0: stdin (will be written on stdout) 613 - 1: stdout 614 - 2: stderr 615 616 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 617 the uint32 size encoded as big endian. 618 619 **PAYLOAD** 620 621 The payload is the raw stream. 622 623 **IMPLEMENTATION** 624 625 The simplest way to implement the Attach protocol is the following: 626 627 1. Read 8 bytes 628 2. chose stdout or stderr depending on the first byte 629 3. Extract the frame size from the last 4 bytes 630 4. Read the extracted size and output it on the correct output 631 5. Goto 1 632 633 ### Attach to a container (websocket) 634 635 `GET /containers/(id)/attach/ws` 636 637 Attach to the container `id` via websocket 638 639 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 640 641 **Example request** 642 643 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 644 645 **Example response** 646 647 {{ STREAM }} 648 649 Query Parameters: 650 651 - **logs** – 1/True/true or 0/False/false, return logs. Default false 652 - **stream** – 1/True/true or 0/False/false, return stream. 653 Default false 654 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 655 to stdin. Default false 656 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 657 stdout log, if stream=true, attach to stdout. Default false 658 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 659 stderr log, if stream=true, attach to stderr. Default false 660 661 Status Codes: 662 663 - **200** – no error 664 - **400** – bad parameter 665 - **404** – no such container 666 - **500** – server error 667 668 ### Wait a container 669 670 `POST /containers/(id)/wait` 671 672 Block until container `id` stops, then returns the exit code 673 674 **Example request**: 675 676 POST /containers/16253994b7c4/wait HTTP/1.1 677 678 **Example response**: 679 680 HTTP/1.1 200 OK 681 Content-Type: application/json 682 683 {"StatusCode": 0} 684 685 Status Codes: 686 687 - **200** – no error 688 - **404** – no such container 689 - **500** – server error 690 691 ### Remove a container 692 693 `DELETE /containers/(id)` 694 695 Remove the container `id` from the filesystem 696 697 **Example request**: 698 699 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 700 701 **Example response**: 702 703 HTTP/1.1 204 No Content 704 705 Query Parameters: 706 707 - **v** – 1/True/true or 0/False/false, Remove the volumes 708 associated to the container. Default false 709 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 710 Default false 711 712 Status Codes: 713 714 - **204** – no error 715 - **400** – bad parameter 716 - **404** – no such container 717 - **500** – server error 718 719 ### Copy files or folders from a container 720 721 `POST /containers/(id)/copy` 722 723 Copy files or folders of container `id` 724 725 **Example request**: 726 727 POST /containers/4fa6e0f0c678/copy HTTP/1.1 728 Content-Type: application/json 729 730 { 731 "Resource": "test.txt" 732 } 733 734 **Example response**: 735 736 HTTP/1.1 200 OK 737 Content-Type: application/octet-stream 738 739 {{ TAR STREAM }} 740 741 Status Codes: 742 743 - **200** – no error 744 - **404** – no such container 745 - **500** – server error 746 747 ## 2.2 Images 748 749 ### List Images 750 751 `GET /images/json` 752 753 **Example request**: 754 755 GET /images/json?all=0 HTTP/1.1 756 757 **Example response**: 758 759 HTTP/1.1 200 OK 760 Content-Type: application/json 761 762 [ 763 { 764 "RepoTags": [ 765 "ubuntu:12.04", 766 "ubuntu:precise", 767 "ubuntu:latest" 768 ], 769 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 770 "Created": 1365714795, 771 "Size": 131506275, 772 "VirtualSize": 131506275 773 }, 774 { 775 "RepoTags": [ 776 "ubuntu:12.10", 777 "ubuntu:quantal" 778 ], 779 "ParentId": "27cf784147099545", 780 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 781 "Created": 1364102658, 782 "Size": 24653, 783 "VirtualSize": 180116135 784 } 785 ] 786 787 788 Query Parameters: 789 790 - **all** – 1/True/true or 0/False/false, default false 791 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 792 - dangling=true 793 - **filter** - only return images with the specified name 794 795 ### Create an image 796 797 `POST /images/create` 798 799 Create an image, either by pulling it from the registry or by importing it 800 801 **Example request**: 802 803 POST /images/create?fromImage=ubuntu HTTP/1.1 804 805 **Example response**: 806 807 HTTP/1.1 200 OK 808 Content-Type: application/json 809 810 {"status": "Pulling..."} 811 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 812 {"error": "Invalid..."} 813 ... 814 815 When using this endpoint to pull an image from the registry, the 816 `X-Registry-Auth` header can be used to include 817 a base64-encoded AuthConfig object. 818 819 Query Parameters: 820 821 - **fromImage** – name of the image to pull 822 - **fromSrc** – source to import, - means stdin 823 - **repo** – repository 824 - **tag** – tag 825 - **registry** – the registry to pull from 826 827 Request Headers: 828 829 - **X-Registry-Auth** – base64-encoded AuthConfig object 830 831 Status Codes: 832 833 - **200** – no error 834 - **500** – server error 835 836 837 838 ### Inspect an image 839 840 `GET /images/(name)/json` 841 842 Return low-level information on the image `name` 843 844 **Example request**: 845 846 GET /images/ubuntu/json HTTP/1.1 847 848 **Example response**: 849 850 HTTP/1.1 200 OK 851 Content-Type: application/json 852 853 { 854 "Created": "2013-03-23T22:24:18.818426-07:00", 855 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 856 "ContainerConfig": 857 { 858 "Hostname": "", 859 "User": "", 860 "Memory": 0, 861 "MemorySwap": 0, 862 "AttachStdin": false, 863 "AttachStdout": false, 864 "AttachStderr": false, 865 "PortSpecs": null, 866 "Tty": true, 867 "OpenStdin": true, 868 "StdinOnce": false, 869 "Env": null, 870 "Cmd": ["/bin/bash"], 871 "Dns": null, 872 "Image": "ubuntu", 873 "Volumes": null, 874 "VolumesFrom": "", 875 "WorkingDir": "" 876 }, 877 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 878 "Parent": "27cf784147099545", 879 "Size": 6824592 880 } 881 882 Status Codes: 883 884 - **200** – no error 885 - **404** – no such image 886 - **500** – server error 887 888 ### Get the history of an image 889 890 `GET /images/(name)/history` 891 892 Return the history of the image `name` 893 894 **Example request**: 895 896 GET /images/ubuntu/history HTTP/1.1 897 898 **Example response**: 899 900 HTTP/1.1 200 OK 901 Content-Type: application/json 902 903 [ 904 { 905 "Id": "b750fe79269d", 906 "Created": 1364102658, 907 "CreatedBy": "/bin/bash" 908 }, 909 { 910 "Id": "27cf78414709", 911 "Created": 1364068391, 912 "CreatedBy": "" 913 } 914 ] 915 916 Status Codes: 917 918 - **200** – no error 919 - **404** – no such image 920 - **500** – server error 921 922 ### Push an image on the registry 923 924 `POST /images/(name)/push` 925 926 Push the image `name` on the registry 927 928 **Example request**: 929 930 POST /images/test/push HTTP/1.1 931 932 **Example response**: 933 934 HTTP/1.1 200 OK 935 Content-Type: application/json 936 937 {"status": "Pushing..."} 938 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 939 {"error": "Invalid..."} 940 ... 941 942 If you wish to push an image on to a private registry, that image must already have been tagged 943 into a repository which references that registry host name and port. This repository name should 944 then be used in the URL. This mirrors the flow of the CLI. 945 946 **Example request**: 947 948 POST /images/registry.acme.com:5000/test/push HTTP/1.1 949 950 951 Query Parameters: 952 953 - **tag** – the tag to associate with the image on the registry, optional 954 955 Request Headers: 956 957 - **X-Registry-Auth** – include a base64-encoded AuthConfig object. 958 959 Status Codes: 960 961 - **200** – no error 962 - **404** – no such image 963 - **500** – server error 964 965 ### Tag an image into a repository 966 967 `POST /images/(name)/tag` 968 969 Tag the image `name` into a repository 970 971 **Example request**: 972 973 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 974 975 **Example response**: 976 977 HTTP/1.1 201 OK 978 979 Query Parameters: 980 981 - **repo** – The repository to tag in 982 - **force** – 1/True/true or 0/False/false, default false 983 - **tag** - The new tag name 984 985 Status Codes: 986 987 - **201** – no error 988 - **400** – bad parameter 989 - **404** – no such image 990 - **409** – conflict 991 - **500** – server error 992 993 ### Remove an image 994 995 `DELETE /images/(name)` 996 997 Remove the image `name` from the filesystem 998 999 **Example request**: 1000 1001 DELETE /images/test HTTP/1.1 1002 1003 **Example response**: 1004 1005 HTTP/1.1 200 OK 1006 Content-type: application/json 1007 1008 [ 1009 {"Untagged": "3e2f21a89f"}, 1010 {"Deleted": "3e2f21a89f"}, 1011 {"Deleted": "53b4f83ac9"} 1012 ] 1013 1014 Query Parameters: 1015 1016 - **force** – 1/True/true or 0/False/false, default false 1017 - **noprune** – 1/True/true or 0/False/false, default false 1018 1019 Status Codes: 1020 1021 - **200** – no error 1022 - **404** – no such image 1023 - **409** – conflict 1024 - **500** – server error 1025 1026 ### Search images 1027 1028 `GET /images/search` 1029 1030 Search for an image on [Docker Hub](https://hub.docker.com). 1031 1032 > **Note**: 1033 > The response keys have changed from API v1.6 to reflect the JSON 1034 > sent by the registry server to the docker daemon's request. 1035 1036 **Example request**: 1037 1038 GET /images/search?term=sshd HTTP/1.1 1039 1040 **Example response**: 1041 1042 HTTP/1.1 200 OK 1043 Content-Type: application/json 1044 1045 [ 1046 { 1047 "description": "", 1048 "is_official": false, 1049 "is_automated": false, 1050 "name": "wma55/u1210sshd", 1051 "star_count": 0 1052 }, 1053 { 1054 "description": "", 1055 "is_official": false, 1056 "is_automated": false, 1057 "name": "jdswinbank/sshd", 1058 "star_count": 0 1059 }, 1060 { 1061 "description": "", 1062 "is_official": false, 1063 "is_automated": false, 1064 "name": "vgauthier/sshd", 1065 "star_count": 0 1066 } 1067 ... 1068 ] 1069 1070 Query Parameters: 1071 1072 - **term** – term to search 1073 1074 Status Codes: 1075 1076 - **200** – no error 1077 - **500** – server error 1078 1079 ## 2.3 Misc 1080 1081 ### Build an image from Dockerfile via stdin 1082 1083 `POST /build` 1084 1085 Build an image from Dockerfile via stdin 1086 1087 **Example request**: 1088 1089 POST /build HTTP/1.1 1090 1091 {{ TAR STREAM }} 1092 1093 **Example response**: 1094 1095 HTTP/1.1 200 OK 1096 Content-Type: application/json 1097 1098 {"stream": "Step 1..."} 1099 {"stream": "..."} 1100 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1101 1102 The stream must be a tar archive compressed with one of the 1103 following algorithms: identity (no compression), gzip, bzip2, xz. 1104 1105 The archive must include a file called `Dockerfile` 1106 at its root. It may include any number of other files, 1107 which will be accessible in the build context (See the [*ADD build 1108 command*](../../reference/builder.md#dockerbuilder)). 1109 1110 Query Parameters: 1111 1112 - **t** – repository name (and optionally a tag) to be applied to 1113 the resulting image in case of success 1114 - **remote** – git or HTTP/HTTPS URI build source 1115 - **q** – suppress verbose build output 1116 - **nocache** – do not use the cache when building the image 1117 - **rm** - remove intermediate containers after a successful build (default behavior) 1118 - **forcerm** - always remove intermediate containers (includes rm) 1119 1120 Request Headers: 1121 1122 - **Content-type** – should be set to `"application/tar"`. 1123 - **X-Registry-Config** – base64-encoded ConfigFile object 1124 1125 Status Codes: 1126 1127 - **200** – no error 1128 - **500** – server error 1129 1130 ### Check auth configuration 1131 1132 `POST /auth` 1133 1134 Get the default username and email 1135 1136 **Example request**: 1137 1138 POST /auth HTTP/1.1 1139 Content-Type: application/json 1140 1141 { 1142 "username":" hannibal", 1143 "password: "xxxx", 1144 "email": "hannibal@a-team.com", 1145 "serveraddress": "https://index.docker.io/v1/" 1146 } 1147 1148 **Example response**: 1149 1150 HTTP/1.1 200 OK 1151 1152 Status Codes: 1153 1154 - **200** – no error 1155 - **204** – no error 1156 - **500** – server error 1157 1158 ### Display system-wide information 1159 1160 `GET /info` 1161 1162 Display system-wide information 1163 1164 **Example request**: 1165 1166 GET /info HTTP/1.1 1167 1168 **Example response**: 1169 1170 HTTP/1.1 200 OK 1171 Content-Type: application/json 1172 1173 { 1174 "Containers": 11, 1175 "Images": 16, 1176 "Driver": "btrfs", 1177 "ExecutionDriver": "native-0.1", 1178 "KernelVersion": "3.12.0-1-amd64" 1179 "Debug": false, 1180 "NFd": 11, 1181 "NGoroutines": 21, 1182 "NEventsListener": 0, 1183 "InitPath": "/usr/bin/docker", 1184 "IndexServerAddress": ["https://index.docker.io/v1/"], 1185 "MemoryLimit": true, 1186 "SwapLimit": false, 1187 "IPv4Forwarding": true 1188 } 1189 1190 Status Codes: 1191 1192 - **200** – no error 1193 - **500** – server error 1194 1195 ### Show the docker version information 1196 1197 `GET /version` 1198 1199 Show the docker version information 1200 1201 **Example request**: 1202 1203 GET /version HTTP/1.1 1204 1205 **Example response**: 1206 1207 HTTP/1.1 200 OK 1208 Content-Type: application/json 1209 1210 { 1211 "ApiVersion": "1.12", 1212 "Version": "0.2.2", 1213 "GitCommit": "5a2a5cc+CHANGES", 1214 "GoVersion": "go1.0.3" 1215 } 1216 1217 Status Codes: 1218 1219 - **200** – no error 1220 - **500** – server error 1221 1222 ### Ping the docker server 1223 1224 `GET /_ping` 1225 1226 Ping the docker server 1227 1228 **Example request**: 1229 1230 GET /_ping HTTP/1.1 1231 1232 **Example response**: 1233 1234 HTTP/1.1 200 OK 1235 Content-Type: text/plain 1236 1237 OK 1238 1239 Status Codes: 1240 1241 - **200** - no error 1242 - **500** - server error 1243 1244 ### Create a new image from a container's changes 1245 1246 `POST /commit` 1247 1248 Create a new image from a container's changes 1249 1250 **Example request**: 1251 1252 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1253 Content-Type: application/json 1254 1255 { 1256 "Hostname": "", 1257 "Domainname": "", 1258 "User": "", 1259 "Memory": 0, 1260 "MemorySwap": 0, 1261 "CpuShares": 512, 1262 "Cpuset": "0,1", 1263 "AttachStdin": false, 1264 "AttachStdout": true, 1265 "AttachStderr": true, 1266 "PortSpecs": null, 1267 "Tty": false, 1268 "OpenStdin": false, 1269 "StdinOnce": false, 1270 "Env": null, 1271 "Cmd": [ 1272 "date" 1273 ], 1274 "Volumes": { 1275 "/tmp": {} 1276 }, 1277 "WorkingDir": "", 1278 "NetworkDisabled": false, 1279 "ExposedPorts": { 1280 "22/tcp": {} 1281 } 1282 } 1283 1284 **Example response**: 1285 1286 HTTP/1.1 201 Created 1287 Content-Type: application/json 1288 1289 {"Id": "596069db4bf5"} 1290 1291 Json Parameters: 1292 1293 - **config** - the container's configuration 1294 1295 Query Parameters: 1296 1297 - **container** – source container 1298 - **repo** – repository 1299 - **tag** – tag 1300 - **comment** – commit message 1301 - **author** – author (e.g., "John Hannibal Smith 1302 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1303 1304 Status Codes: 1305 1306 - **201** – no error 1307 - **404** – no such container 1308 - **500** – server error 1309 1310 ### Monitor Docker's events 1311 1312 `GET /events` 1313 1314 Get container events from docker, either in real time via streaming, or via 1315 polling (using since). 1316 1317 Docker containers will report the following events: 1318 1319 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1320 1321 and Docker images will report: 1322 1323 untag, delete 1324 1325 **Example request**: 1326 1327 GET /events?since=1374067924 1328 1329 **Example response**: 1330 1331 HTTP/1.1 200 OK 1332 Content-Type: application/json 1333 1334 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1335 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1336 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1337 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1338 1339 Query Parameters: 1340 1341 - **since** – timestamp used for polling 1342 - **until** – timestamp used for polling 1343 1344 Status Codes: 1345 1346 - **200** – no error 1347 - **500** – server error 1348 1349 ### Get a tarball containing all images and tags in a repository 1350 1351 `GET /images/(name)/get` 1352 1353 Get a tarball containing all images and metadata for the repository 1354 specified by `name`. 1355 1356 See the [image tarball format](#image-tarball-format) for more details. 1357 1358 **Example request** 1359 1360 GET /images/ubuntu/get 1361 1362 **Example response**: 1363 1364 HTTP/1.1 200 OK 1365 Content-Type: application/x-tar 1366 1367 Binary data stream 1368 1369 Status Codes: 1370 1371 - **200** – no error 1372 - **500** – server error 1373 1374 ### Load a tarball with a set of images and tags into docker 1375 1376 `POST /images/load` 1377 1378 Load a set of images and tags into the docker repository. 1379 See the [image tarball format](#image-tarball-format) for more details. 1380 1381 **Example request** 1382 1383 POST /images/load 1384 1385 Tarball in body 1386 1387 **Example response**: 1388 1389 HTTP/1.1 200 OK 1390 1391 Status Codes: 1392 1393 - **200** – no error 1394 - **500** – server error 1395 1396 ### Image tarball format 1397 1398 An image tarball contains one directory per image layer (named using its long ID), 1399 each containing three files: 1400 1401 1. `VERSION`: currently `1.0` - the file format version 1402 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1403 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1404 1405 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1406 for storing attribute changes and deletions. 1407 1408 If the tarball defines a repository, there will also be a `repositories` file at 1409 the root that contains a list of repository and tag names mapped to layer IDs. 1410 1411 ``` 1412 {"hello-world": 1413 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1414 } 1415 ``` 1416 1417 # 3. Going further 1418 1419 ## 3.1 Inside `docker run` 1420 1421 As an example, the `docker run` command line makes the following API calls: 1422 1423 - Create the container 1424 1425 - If the status code is 404, it means the image doesn't exist: 1426 - Try to pull it 1427 - Then retry to create the container 1428 1429 - Start the container 1430 1431 - If you are not in detached mode: 1432 - Attach to the container, using logs=1 (to have stdout and 1433 stderr from the container's start) and stream=1 1434 1435 - If in detached mode or only stdin is attached: 1436 - Display the container's id 1437 1438 ## 3.2 Hijacking 1439 1440 In this version of the API, /attach, uses hijacking to transport stdin, 1441 stdout and stderr on the same socket. This might change in the future. 1442 1443 ## 3.3 CORS Requests 1444 1445 To enable cross origin requests to the remote api add the flag 1446 "--api-enable-cors" when running docker in daemon mode. 1447 1448 $ docker -d -H="192.168.1.9:2375" --api-enable-cors