github.com/rsampaio/docker@v0.7.2-0.20150827203920-fdc73cc3fc31/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  
    84  
    85  ### v1.20 API changes
    86  
    87  [Docker Remote API v1.20](/reference/api/docker_remote_api_v1.20/) documentation
    88  
    89  * `GET /containers/(id)/archive` get an archive of filesystem content from a container.
    90  * `PUT /containers/(id)/archive` upload an archive of content to be extracted to
    91  an existing directory inside a container's filesystem.
    92  * `POST /containers/(id)/copy` is deprecated in favor of the above `archive`
    93  endpoint which can be used to download files and directories from a container.
    94  * The `hostConfig` option now accepts the field `GroupAdd`, which specifies a
    95  list of additional groups that the container process will run as.
    96  
    97  ### v1.19 API changes
    98  
    99  [Docker Remote API v1.19](/reference/api/docker_remote_api_v1.19/) documentation
   100  
   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  * `GET /containers/(id)/stats` now accepts `stream` bool to get only one set of stats and disconnect.
   105  * `GET /containers/(id)/logs` now accepts a `since` timestamp parameter.
   106  * `GET /info` The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and
   107  `SwapLimit` are now returned as boolean instead of as an int. In addition, the
   108  end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and
   109  `OomKillDisable`.
   110  
   111  ### v1.18 API changes
   112  
   113  [Docker Remote API v1.18](/reference/api/docker_remote_api_v1.18/) documentation
   114  
   115  * `GET /version` now returns `Os`, `Arch` and `KernelVersion`.
   116  * `POST /containers/create` and `POST /containers/(id)/start`allow you to  set ulimit settings for use in the container.
   117  * `GET /info` now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
   118  * `GET /images/json` added a `RepoDigests` field to include image digest information.
   119  * `POST /build` can now set resource constraints for all containers created for the build.
   120  * `CgroupParent` can be passed in the host config to setup container cgroups under a specific cgroup.
   121  * `POST /build` closing the HTTP request cancels the build
   122  * `POST /containers/(id)/exec` includes `Warnings` field to response.
   123  
   124  ### v1.17 API changes
   125  
   126  [Docker Remote API v1.17](/reference/api/docker_remote_api_v1.17/) documentation
   127  
   128  * The build supports `LABEL` command. Use this to add metadata to an image. For
   129  example you could add data describing the content of an image. `LABEL
   130  "com.example.vendor"="ACME Incorporated"`
   131  * `POST /containers/(id)/attach` and `POST /exec/(id)/start`
   132  * The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
   133  * `POST /containers/create` sets labels on container create describing the container.
   134  * `GET /containers/json` returns the labels associated with the containers (`Labels`).
   135  * `GET /containers/(id)/json` returns the list current execs associated with the
   136  container (`ExecIDs`). This endpoint now returns the container labels
   137  (`Config.Labels`).
   138  * `POST /containers/(id)/rename` renames a container `id` to a new name.* 
   139  * `POST /containers/create` and `POST /containers/(id)/start` callers can pass
   140  `ReadonlyRootfs` in the host config to mount the container's root filesystem as
   141  read only.
   142  * `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics.
   143  * `GET /images/json` returns the labels associated with each image (`Labels`).
   144  
   145  
   146  ### v1.16 API changes
   147  
   148  [Docker Remote API v1.16](/reference/api/docker_remote_api_v1.16/)
   149  
   150  * `GET /info` returns the number of CPUs available on the machine (`NCPU`),
   151  total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and
   152  a list of daemon labels (`Labels`).
   153  * `POST /containers/create` callers can set the new container's MAC address explicitly.
   154  * Volumes are now initialized when the container is created.
   155  * `POST /containers/(id)/copy` copies data which is contained in a volume.
   156  
   157  ### v1.15 API changes
   158  
   159  [Docker Remote API v1.15](/reference/api/docker_remote_api_v1.15/) documentation
   160  
   161  `POST /containers/create` you can set a container's `HostConfig` when creating a
   162  container. Previously this was only available when starting a container.
   163  
   164  ### v1.14 API changes
   165  
   166  [Docker Remote API v1.14](/reference/api/docker_remote_api_v1.14/) documentation
   167  
   168  * `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL.
   169  * `POST /containers/(id)/start` the `hostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities
   170  to add, and the field `CapDrop`, which specifies a list of capabilities to drop.
   171  * `POST /images/create` th `fromImage` and `repo` parameters supportthe
   172  `repo:tag` format. Consequently,  the `tag` parameter is now obsolete. Using the
   173  new format and the `tag` parameter at the same time will return an error.
   174  
   175  
   176