github.com/wulonghui/docker@v1.8.0-rc2/docs/reference/api/docker_remote_api.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Remote API" 4 description = "API Documentation for Docker" 5 keywords = ["API, Docker, rcli, REST, documentation"] 6 [menu.main] 7 parent = "smn_remoteapi" 8 +++ 9 <![end-metadata]--> 10 11 # Docker Remote API 12 13 - By default the Docker daemon listens on `unix:///var/run/docker.sock` 14 and the client must have `root` access to interact with the daemon. 15 - If the Docker daemon is set to use an encrypted TCP socket (`--tls`, 16 or `--tlsverify`) as with Boot2Docker 1.3.0, then you need to add extra 17 parameters to `curl` or `wget` when making test API requests: 18 `curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://boot2docker:2376/images/json` 19 or 20 `wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem --private-key=$DOCKER_CERT_PATH/key.pem https://boot2docker:2376/images/json -O - -q` 21 - If a group named `docker` exists on your system, docker will apply 22 ownership of the socket to the group. 23 - The API tends to be REST, but for some complex commands, like attach 24 or pull, the HTTP connection is hijacked to transport STDOUT, STDIN, 25 and STDERR. 26 - Since API version 1.2, the auth configuration is now handled client 27 side, so the client has to send the `authConfig` as a `POST` in `/images/(name)/push`. 28 - authConfig, set as the `X-Registry-Auth` header, is currently a Base64 29 encoded (JSON) string with the following structure: 30 `{"username": "string", "password": "string", "email": "string", 31 "serveraddress" : "string", "auth": ""}`. Notice that `auth` is to be left 32 empty, `serveraddress` is a domain/ip without protocol, and that double 33 quotes (instead of single ones) are required. 34 - The Remote API uses an open schema model. In this model, unknown 35 properties in incoming messages will be ignored. 36 Client applications need to take this into account to ensure 37 they will not break when talking to newer Docker daemons. 38 39 The current version of the API is v1.20 40 41 Calling `/info` is the same as calling 42 `/v1.20/info`. 43 44 You can still call an old version of the API using 45 `/v1.19/info`. 46 47 ## Docker Events 48 49 The following diagram depicts the container states accessible through the API. 50 51  52 53 Some container-related events are not affected by container state, so they are not included in this diagram. These events are: 54 55 * **export** emitted by `docker export` 56 * **exec_create** emitted by `docker exec` 57 * **exec_start** emitted by `docker exec` after **exec_create** 58 59 Running `docker rmi` emits an **untag** event when removing an image name. The `rmi` command may also emit **delete** events when images are deleted by ID directly or by deleting the last tag referring to the image. 60 61 > **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](http://gliderlabs.com/blog/2015/04/14/docker-events-explained/). 62 63 ## v1.20 64 65 ### Full documentation 66 67 [*Docker Remote API v1.20*](/reference/api/docker_remote_api_v1.20/) 68 69 ### What's new 70 71 `GET /containers/(id)/archive` 72 73 **New!** 74 Get an archive of filesystem content from a container. 75 76 `PUT /containers/(id)/archive` 77 78 **New!** 79 Upload an archive of content to be extracted to an 80 existing directory inside a container's filesystem. 81 82 `POST /containers/(id)/copy` 83 84 **Deprecated!** 85 This copy endpoint has been deprecated in favor of the above `archive` endpoint 86 which can be used to download files and directories from a container. 87 88 **New!** 89 The `hostConfig` option now accepts the field `GroupAdd`, which specifies a list of additional 90 groups that the container process will run as. 91 92 ## v1.19 93 94 ### Full documentation 95 96 [*Docker Remote API v1.19*](/reference/api/docker_remote_api_v1.19/) 97 98 ### What's new 99 100 **New!** 101 When the daemon detects a version mismatch with the client, usually when 102 the client is newer than the daemon, an HTTP 400 is now returned instead 103 of a 404. 104 105 `GET /containers/(id)/stats` 106 107 **New!** 108 You can now supply a `stream` bool to get only one set of stats and 109 disconnect 110 111 `GET /containers/(id)/logs` 112 113 **New!** 114 115 This endpoint now accepts a `since` timestamp parameter. 116 117 `GET /info` 118 119 **New!** 120 121 The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and `SwapLimit` 122 are now returned as boolean instead of as an int. 123 124 In addition, the end point now returns the new boolean fields 125 `CpuCfsPeriod`, `CpuCfsQuota`, and `OomKillDisable`. 126 127 ## v1.18 128 129 ### Full documentation 130 131 [*Docker Remote API v1.18*](/reference/api/docker_remote_api_v1.18/) 132 133 ### What's new 134 135 `GET /version` 136 137 **New!** 138 This endpoint now returns `Os`, `Arch` and `KernelVersion`. 139 140 `POST /containers/create` 141 142 `POST /containers/(id)/start` 143 144 **New!** 145 You can set ulimit settings to be used within the container. 146 147 `GET /info` 148 149 **New!** 150 This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`. 151 152 `GET /images/json` 153 154 **New!** 155 Added a `RepoDigests` field to include image digest information. 156 157 `POST /build` 158 159 **New!** 160 Builds can now set resource constraints for all containers created for the build. 161 162 **New!** 163 (`CgroupParent`) can be passed in the host config to setup container cgroups under a specific cgroup. 164 165 `POST /build` 166 167 **New!** 168 Closing the HTTP request will now cause the build to be canceled. 169 170 `POST /containers/(id)/exec` 171 172 **New!** 173 Add `Warnings` field to response. 174 175 ## v1.17 176 177 ### Full documentation 178 179 [*Docker Remote API v1.17*](/reference/api/docker_remote_api_v1.17/) 180 181 ### What's new 182 183 The build supports `LABEL` command. Use this to add metadata 184 to an image. For example you could add data describing the content of an image. 185 186 `LABEL "com.example.vendor"="ACME Incorporated"` 187 188 **New!** 189 `POST /containers/(id)/attach` and `POST /exec/(id)/start` 190 191 **New!** 192 Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers. 193 194 `POST /containers/create` 195 196 **New!** 197 You can set labels on container create describing the container. 198 199 `GET /containers/json` 200 201 **New!** 202 The endpoint returns the labels associated with the containers (`Labels`). 203 204 `GET /containers/(id)/json` 205 206 **New!** 207 This endpoint now returns the list current execs associated with the container (`ExecIDs`). 208 This endpoint now returns the container labels (`Config.Labels`). 209 210 `POST /containers/(id)/rename` 211 212 **New!** 213 New endpoint to rename a container `id` to a new name. 214 215 `POST /containers/create` 216 `POST /containers/(id)/start` 217 218 **New!** 219 (`ReadonlyRootfs`) can be passed in the host config to mount the container's 220 root filesystem as read only. 221 222 `GET /containers/(id)/stats` 223 224 **New!** 225 This endpoint returns a live stream of a container's resource usage statistics. 226 227 `GET /images/json` 228 229 **New!** 230 This endpoint now returns the labels associated with each image (`Labels`). 231 232 233 ## v1.16 234 235 ### Full documentation 236 237 [*Docker Remote API v1.16*](/reference/api/docker_remote_api_v1.16/) 238 239 ### What's new 240 241 `GET /info` 242 243 **New!** 244 `info` now returns the number of CPUs available on the machine (`NCPU`), 245 total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and 246 a list of daemon labels (`Labels`). 247 248 `POST /containers/create` 249 250 **New!** 251 You can set the new container's MAC address explicitly. 252 253 **New!** 254 Volumes are now initialized when the container is created. 255 256 `POST /containers/(id)/copy` 257 258 **New!** 259 You can now copy data which is contained in a volume. 260 261 ## v1.15 262 263 ### Full documentation 264 265 [*Docker Remote API v1.15*](/reference/api/docker_remote_api_v1.15/) 266 267 ### What's new 268 269 `POST /containers/create` 270 271 **New!** 272 It is now possible to set a container's HostConfig when creating a container. 273 Previously this was only available when starting a container. 274 275 ## v1.14 276 277 ### Full documentation 278 279 [*Docker Remote API v1.14*](/reference/api/docker_remote_api_v1.14/) 280 281 ### What's new 282 283 `DELETE /containers/(id)` 284 285 **New!** 286 When using `force`, the container will be immediately killed with SIGKILL. 287 288 `POST /containers/(id)/start` 289 290 **New!** 291 The `hostConfig` option now accepts the field `CapAdd`, which specifies a list of capabilities 292 to add, and the field `CapDrop`, which specifies a list of capabilities to drop. 293 294 `POST /images/create` 295 296 **New!** 297 The `fromImage` and `repo` parameters now supports the `repo:tag` format. 298 Consequently, the `tag` parameter is now obsolete. Using the new format and 299 the `tag` parameter at the same time will return an error. 300 301 ## v1.13 302 303 ### Full documentation 304 305 [*Docker Remote API v1.13*](/reference/api/docker_remote_api_v1.13/) 306 307 ### What's new 308 309 `GET /containers/(name)/json` 310 311 **New!** 312 The `HostConfig.Links` field is now filled correctly 313 314 **New!** 315 `Sockets` parameter added to the `/info` endpoint listing all the sockets the 316 daemon is configured to listen on. 317 318 `POST /containers/(name)/start` 319 `POST /containers/(name)/stop` 320 321 **New!** 322 `start` and `stop` will now return 304 if the container's status is not modified 323 324 `POST /commit` 325 326 **New!** 327 Added a `pause` parameter (default `true`) to pause the container during commit 328 329 ## v1.12 330 331 ### Full documentation 332 333 [*Docker Remote API v1.12*](/reference/api/docker_remote_api_v1.12/) 334 335 ### What's new 336 337 `POST /build` 338 339 **New!** 340 Build now has support for the `forcerm` parameter to always remove containers 341 342 `GET /containers/(name)/json` 343 `GET /images/(name)/json` 344 345 **New!** 346 All the JSON keys are now in CamelCase 347 348 **New!** 349 Trusted builds are now Automated Builds - `is_trusted` is now `is_automated`. 350 351 **Removed Insert Endpoint** 352 The `insert` endpoint has been removed. 353 354 ## v1.11 355 356 ### Full documentation 357 358 [*Docker Remote API v1.11*](/reference/api/docker_remote_api_v1.11/) 359 360 ### What's new 361 362 `GET /_ping` 363 364 **New!** 365 You can now ping the server via the `_ping` endpoint. 366 367 `GET /events` 368 369 **New!** 370 You can now use the `-until` parameter to close connection 371 after timestamp. 372 373 `GET /containers/(id)/logs` 374 375 This url is preferred method for getting container logs now. 376 377 ## v1.10 378 379 ### Full documentation 380 381 [*Docker Remote API v1.10*](/reference/api/docker_remote_api_v1.10/) 382 383 ### What's new 384 385 `DELETE /images/(name)` 386 387 **New!** 388 You can now use the force parameter to force delete of an 389 image, even if it's tagged in multiple repositories. **New!** 390 You 391 can now use the noprune parameter to prevent the deletion of parent 392 images 393 394 `DELETE /containers/(id)` 395 396 **New!** 397 You can now use the force parameter to force delete a 398 container, even if it is currently running 399 400 ## v1.9 401 402 ### Full documentation 403 404 [*Docker Remote API v1.9*](/reference/api/docker_remote_api_v1.9/) 405 406 ### What's new 407 408 `POST /build` 409 410 **New!** 411 This endpoint now takes a serialized ConfigFile which it 412 uses to resolve the proper registry auth credentials for pulling the 413 base image. Clients which previously implemented the version 414 accepting an AuthConfig object must be updated. 415 416 ## v1.8 417 418 ### Full documentation 419 420 [*Docker Remote API v1.8*](/reference/api/docker_remote_api_v1.8/) 421 422 ### What's new 423 424 `POST /build` 425 426 **New!** 427 This endpoint now returns build status as json stream. In 428 case of a build error, it returns the exit status of the failed 429 command. 430 431 `GET /containers/(id)/json` 432 433 **New!** 434 This endpoint now returns the host config for the 435 container. 436 437 `POST /images/create` 438 439 `POST /images/(name)/insert` 440 441 `POST /images/(name)/push` 442 443 **New!** 444 progressDetail object was added in the JSON. It's now 445 possible to get the current value and the total of the progress 446 without having to parse the string. 447 448 ## v1.7 449 450 ### Full documentation 451 452 [*Docker Remote API v1.7*](/reference/api/docker_remote_api_v1.7/) 453 454 ### What's new 455 456 `GET /images/json` 457 458 The format of the json returned from this uri changed. Instead of an 459 entry for each repo/tag on an image, each image is only represented 460 once, with a nested attribute indicating the repo/tags that apply to 461 that image. 462 463 Instead of: 464 465 HTTP/1.1 200 OK 466 Content-Type: application/json 467 468 [ 469 { 470 "VirtualSize": 131506275, 471 "Size": 131506275, 472 "Created": 1365714795, 473 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 474 "Tag": "12.04", 475 "Repository": "ubuntu" 476 }, 477 { 478 "VirtualSize": 131506275, 479 "Size": 131506275, 480 "Created": 1365714795, 481 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 482 "Tag": "latest", 483 "Repository": "ubuntu" 484 }, 485 { 486 "VirtualSize": 131506275, 487 "Size": 131506275, 488 "Created": 1365714795, 489 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 490 "Tag": "precise", 491 "Repository": "ubuntu" 492 }, 493 { 494 "VirtualSize": 180116135, 495 "Size": 24653, 496 "Created": 1364102658, 497 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 498 "Tag": "12.10", 499 "Repository": "ubuntu" 500 }, 501 { 502 "VirtualSize": 180116135, 503 "Size": 24653, 504 "Created": 1364102658, 505 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 506 "Tag": "quantal", 507 "Repository": "ubuntu" 508 } 509 ] 510 511 The returned json looks like this: 512 513 HTTP/1.1 200 OK 514 Content-Type: application/json 515 516 [ 517 { 518 "RepoTags": [ 519 "ubuntu:12.04", 520 "ubuntu:precise", 521 "ubuntu:latest" 522 ], 523 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 524 "Created": 1365714795, 525 "Size": 131506275, 526 "VirtualSize": 131506275 527 }, 528 { 529 "RepoTags": [ 530 "ubuntu:12.10", 531 "ubuntu:quantal" 532 ], 533 "ParentId": "27cf784147099545", 534 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 535 "Created": 1364102658, 536 "Size": 24653, 537 "VirtualSize": 180116135 538 } 539 ] 540 541 `GET /images/viz` 542 543 This URI no longer exists. The `images --viz` 544 output is now generated in the client, using the 545 `/images/json` data. 546 547 ## v1.6 548 549 ### Full documentation 550 551 [*Docker Remote API v1.6*](/reference/api/docker_remote_api_v1.6/) 552 553 ### What's new 554 555 `POST /containers/(id)/attach` 556 557 **New!** 558 You can now split stderr from stdout. This is done by 559 prefixing a header to each transmission. See 560 [`POST /containers/(id)/attach`]( 561 /reference/api/docker_remote_api_v1.9/#attach-to-a-container "POST /containers/(id)/attach"). 562 The WebSocket attach is unchanged. Note that attach calls on the 563 previous API version didn't change. Stdout and stderr are merged. 564 565 ## v1.5 566 567 ### Full documentation 568 569 [*Docker Remote API v1.5*](/reference/api/docker_remote_api_v1.5/) 570 571 ### What's new 572 573 `POST /images/create` 574 575 **New!** 576 You can now pass registry credentials (via an AuthConfig 577 object) through the X-Registry-Auth header 578 579 `POST /images/(name)/push` 580 581 **New!** 582 The AuthConfig object now needs to be passed through the 583 X-Registry-Auth header 584 585 `GET /containers/json` 586 587 **New!** 588 The format of the Ports entry has been changed to a list of 589 dicts each containing PublicPort, PrivatePort and Type describing a 590 port mapping. 591 592 ## v1.4 593 594 ### Full documentation 595 596 [*Docker Remote API v1.4*](/reference/api/docker_remote_api_v1.4/) 597 598 ### What's new 599 600 `POST /images/create` 601 602 **New!** 603 When pulling a repo, all images are now downloaded in parallel. 604 605 `GET /containers/(id)/top` 606 607 **New!** 608 You can now use ps args with docker top, like docker top 609 <container_id> aux 610 611 `GET /events` 612 613 **New!** 614 Image's name added in the events 615 616 ## v1.3 617 618 docker v0.5.0 619 [51f6c4a](https://github.com/docker/docker/commit/51f6c4a7372450d164c61e0054daf0223ddbd909) 620 621 ### Full documentation 622 623 [*Docker Remote API v1.3*](/reference/api/docker_remote_api_v1.3/) 624 625 ### What's new 626 627 `GET /containers/(id)/top` 628 629 List the processes running inside a container. 630 631 `GET /events` 632 633 **New!** 634 Monitor docker's events via streaming or via polling 635 636 Builder (/build): 637 638 - Simplify the upload of the build context 639 - Simply stream a tarball instead of multipart upload with 4 640 intermediary buffers 641 - Simpler, less memory usage, less disk usage and faster 642 643 > **Warning**: 644 > The /build improvements are not reverse-compatible. Pre 1.3 clients will 645 > break on /build. 646 647 List containers (/containers/json): 648 649 - You can use size=1 to get the size of the containers 650 651 Start containers (/containers/<id>/start): 652 653 - You can now pass host-specific configuration (e.g., bind mounts) in 654 the POST body for start calls 655 656 ## v1.2 657 658 docker v0.4.2 659 [2e7649b](https://github.com/docker/docker/commit/2e7649beda7c820793bd46766cbc2cfeace7b168) 660 661 ### Full documentation 662 663 [*Docker Remote API v1.2*](/reference/api/docker_remote_api_v1.2/) 664 665 ### What's new 666 667 The auth configuration is now handled by the client. 668 669 The client should send it's authConfig as POST on each call of 670 `/images/(name)/push` 671 672 `GET /auth` 673 674 **Deprecated.** 675 676 `POST /auth` 677 678 Only checks the configuration but doesn't store it on the server 679 680 Deleting an image is now improved, will only untag the image if it 681 has children and remove all the untagged parents if has any. 682 683 `POST /images/<name>/delete` 684 685 Now returns a JSON structure with the list of images 686 deleted/untagged. 687 688 ## v1.1 689 690 docker v0.4.0 691 [a8ae398](https://github.com/docker/docker/commit/a8ae398bf52e97148ee7bd0d5868de2e15bd297f) 692 693 ### Full documentation 694 695 [*Docker Remote API v1.1*](/reference/api/docker_remote_api_v1.1/) 696 697 ### What's new 698 699 `POST /images/create` 700 701 `POST /images/(name)/insert` 702 703 `POST /images/(name)/push` 704 705 Uses json stream instead of HTML hijack, it looks like this: 706 707 HTTP/1.1 200 OK 708 Content-Type: application/json 709 710 {"status":"Pushing..."} 711 {"status":"Pushing", "progress":"1/? (n/a)"} 712 {"error":"Invalid..."} 713 ... 714 715 ## v1.0 716 717 docker v0.3.4 718 [8d73740](https://github.com/docker/docker/commit/8d73740343778651c09160cde9661f5f387b36f4) 719 720 ### Full documentation 721 722 [*Docker Remote API v1.0*](/reference/api/docker_remote_api_v1.0/) 723 724 ### What's new 725 726 Initial version