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