github.com/mheon/docker@v0.11.2-0.20150922122814-44f47903a831/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  Docker's Remote API uses an open schema model.  In this model, unknown 
    14  properties in incoming messages are ignored. Client applications need to take
    15  this behavior into account to ensure they do not break when talking to newer
    16  Docker daemons.
    17  
    18  The API tends to be REST, but for some complex commands, like attach or pull,
    19  the HTTP connection is hijacked to transport STDOUT, STDIN, and STDERR.
    20     
    21  By default the Docker daemon listens on `unix:///var/run/docker.sock` and the
    22  client must have `root` access to interact with the daemon. If a group named
    23  `docker` exists on your system, `docker` applies ownership of the socket to the
    24  group.
    25  
    26  The current version of the API is v1.21 which means calling `/info` is the same
    27  as calling `/v1.21/info`. To call an older version of the API use
    28  `/v1.20/info`.
    29  
    30  ## Authentication
    31  
    32  Since API version 1.2, the auth configuration is now handled client side, so the
    33  client has to send the `authConfig` as a `POST` in `/images/(name)/push`. The
    34  `authConfig`, set as the `X-Registry-Auth` header, is currently a Base64 encoded
    35  (JSON) string with the following structure:
    36  
    37  ```
    38  {"username": "string", "password": "string", "email": "string",
    39     "serveraddress" : "string", "auth": ""}
    40  ```
    41     
    42  Callers should leave the `auth` empty. The `serveraddress` is a domain/ip
    43  without protocol. Throughout this structure, double quotes are required.
    44  
    45  ## Using Docker Machine with the API
    46  
    47  If you are using `docker-machine`, the Docker daemon is on a virtual host that uses an encrypted TCP socket. This means, for Docker Machine users, you need to add extra parameters to `curl` or `wget` when making test API requests, for example:
    48  
    49  ```
    50  curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://YOUR_VM_IP:2376/images/json
    51  
    52  wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem --private-key=$DOCKER_CERT_PATH/key.pem https://your_vm_ip:2376/images/json -O - -q
    53  ```
    54  
    55  ## Docker Events
    56  
    57  The following diagram depicts the container states accessible through the API.
    58  
    59  ![States](../images/event_state.png)
    60  
    61  Some container-related events are not affected by container state, so they are not included in this diagram. These events are:
    62  
    63  * **export** emitted by `docker export`
    64  * **exec_create** emitted by `docker exec`
    65  * **exec_start** emitted by `docker exec` after **exec_create**
    66  
    67  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.
    68  
    69  > **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/).
    70  
    71  ## Version history
    72  
    73  This section lists each version from latest to oldest.  Each listing includes a link to the full documentation set and the changes relevant in that release.
    74  
    75  ### v1.21 API changes
    76  
    77  [Docker Remote API v1.21](/reference/api/docker_remote_api_v1.21/) documentation
    78  
    79  * `GET /volumes` lists volumes from all volume drivers.
    80  * `POST /volumes` to create a volume.
    81  * `GET /volumes/(name)` get low-level information about a volume.
    82  * `DELETE /volumes/(name)`remove a volume with the specified name.
    83  * `VolumeDriver` has been moved from config to hostConfig to make the configuration portable.
    84  * `GET /images/(name)/json` now returns information about tags of the image.
    85  * The `config` option now accepts the field `StopSignal`, which specifies the signal to use to kill a container.
    86  * `GET /containers/(id)/stats` will return networking information respectively for each interface.
    87  * The `hostConfig` option now accepts the field `DnsOptions`, which specifies a
    88  list of DNS options to be used in the container.
    89  * `POST /build` now optionally takes a serialized map of build-time variables.
    90  * `GET /events` now includes a `timenano` field, in addition to the existing `time` field.
    91  * `GET /info` now lists engine version information.
    92  
    93  ### v1.20 API changes
    94  
    95  [Docker Remote API v1.20](/reference/api/docker_remote_api_v1.20/) documentation
    96  
    97  * `GET /containers/(id)/archive` get an archive of filesystem content from a container.
    98  * `PUT /containers/(id)/archive` upload an archive of content to be extracted to
    99  an existing directory inside a container's filesystem.
   100  * `POST /containers/(id)/copy` is deprecated in favor of the above `archive`
   101  endpoint which can be used to download files and directories from a container.
   102  * The `hostConfig` option now accepts the field `GroupAdd`, which specifies a
   103  list of additional groups that the container process will run as.
   104  
   105  ### v1.19 API changes
   106  
   107  [Docker Remote API v1.19](/reference/api/docker_remote_api_v1.19/) documentation
   108  
   109  * When the daemon detects a version mismatch with the client, usually when
   110  the client is newer than the daemon, an HTTP 400 is now returned instead
   111  of a 404.
   112  * `GET /containers/(id)/stats` now accepts `stream` bool to get only one set of stats and disconnect.
   113  * `GET /containers/(id)/logs` now accepts a `since` timestamp parameter.
   114  * `GET /info` The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and
   115  `SwapLimit` are now returned as boolean instead of as an int. In addition, the
   116  end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and
   117  `OomKillDisable`.
   118  
   119  ### v1.18 API changes
   120  
   121  [Docker Remote API v1.18](/reference/api/docker_remote_api_v1.18/) documentation
   122  
   123  * `GET /version` now returns `Os`, `Arch` and `KernelVersion`.
   124  * `POST /containers/create` and `POST /containers/(id)/start`allow you to  set ulimit settings for use in the container.
   125  * `GET /info` now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
   126  * `GET /images/json` added a `RepoDigests` field to include image digest information.
   127  * `POST /build` can now set resource constraints for all containers created for the build.
   128  * `CgroupParent` can be passed in the host config to setup container cgroups under a specific cgroup.
   129  * `POST /build` closing the HTTP request cancels the build
   130  * `POST /containers/(id)/exec` includes `Warnings` field to response.
   131  
   132  ### v1.17 API changes
   133  
   134  [Docker Remote API v1.17](/reference/api/docker_remote_api_v1.17/) documentation
   135  
   136  * The build supports `LABEL` command. Use this to add metadata to an image. For
   137  example you could add data describing the content of an image. `LABEL
   138  "com.example.vendor"="ACME Incorporated"`
   139  * `POST /containers/(id)/attach` and `POST /exec/(id)/start`
   140  * The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
   141  * `POST /containers/create` sets labels on container create describing the container.
   142  * `GET /containers/json` returns the labels associated with the containers (`Labels`).
   143  * `GET /containers/(id)/json` returns the list current execs associated with the
   144  container (`ExecIDs`). This endpoint now returns the container labels
   145  (`Config.Labels`).
   146  * `POST /containers/(id)/rename` renames a container `id` to a new name.* 
   147  * `POST /containers/create` and `POST /containers/(id)/start` callers can pass
   148  `ReadonlyRootfs` in the host config to mount the container's root filesystem as
   149  read only.
   150  * `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics.
   151  * `GET /images/json` returns the labels associated with each image (`Labels`).
   152  
   153  
   154  ### v1.16 API changes
   155  
   156  [Docker Remote API v1.16](/reference/api/docker_remote_api_v1.16/)
   157  
   158  * `GET /info` returns the number of CPUs available on the machine (`NCPU`),
   159  total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and
   160  a list of daemon labels (`Labels`).
   161  * `POST /containers/create` callers can set the new container's MAC address explicitly.
   162  * Volumes are now initialized when the container is created.
   163  * `POST /containers/(id)/copy` copies data which is contained in a volume.
   164  
   165  ### v1.15 API changes
   166  
   167  [Docker Remote API v1.15](/reference/api/docker_remote_api_v1.15/) documentation
   168  
   169  `POST /containers/create` you can set a container's `HostConfig` when creating a
   170  container. Previously this was only available when starting a container.
   171  
   172  ### v1.14 API changes
   173  
   174  [Docker Remote API v1.14](/reference/api/docker_remote_api_v1.14/) documentation
   175  
   176  * `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL.
   177  * `POST /containers/(id)/start` the `hostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities
   178  to add, and the field `CapDrop`, which specifies a list of capabilities to drop.
   179  * `POST /images/create` th `fromImage` and `repo` parameters supportthe
   180  `repo:tag` format. Consequently,  the `tag` parameter is now obsolete. Using the
   181  new format and the `tag` parameter at the same time will return an error.
   182  
   183  
   184