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