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