github.com/squaremo/docker@v1.3.2-0.20150516120342-42cfc9554972/docs/sources/reference/api/docker_remote_api.md (about)

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