docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API docs cleanup 

fix some formatting issues and consistency;

- Change capitalization (Query Parameters -> Query parameters, Json -> JSON)
- Make Query/JSON parameters and Status codes headings bold
- Fix indentation of some code blocks
- Fix headings (H2 -> H1), although all headings should be shifted the other way
  round ;-)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2016-06-13 16:37:24 +02:00
parent 0b879b993d
commit a4438ca606
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 107 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
docs/reference/api/docker_remote_api_v1.24.md
View File

@ -11,7 +11,7 @@ weight=-5
# Docker Remote API v1.24
## 1. Brief introduction
# 1. Brief introduction
- The Remote API has replaced `rcli`.
- The daemon listens on `unix:///var/run/docker.sock` but you can
@ -212,7 +212,7 @@ List containers
}
]
Query Parameters:
**Query parameters:**
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default (i.e., this defaults to false)
@ -235,7 +235,7 @@ Query Parameters:
- `volume`=(`<volume name>` or `<mount point destination>`)
- `network`=(`<network id>` or `<network name>`)
Status Codes:
**Status codes:**
- **200** – no error
- **400** – bad parameter
@ -357,7 +357,7 @@ Create a container
"Warnings":[]
}
Json Parameters:
**JSON parameters:**
- **Hostname** - A string value containing the hostname to use for the
container.
@ -473,12 +473,12 @@ Json Parameters:
- **VolumeDriver** - Driver that this container users to mount volumes.
- **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
Query Parameters:
**Query parameters:**
- **name** – Assign the specified name to the container. Must
match `/?[a-zA-Z0-9_-]+`.
Status Codes:
**Status codes:**
- **201** – no error
- **400** – bad parameter
@ -684,11 +684,11 @@ Return low-level information on the container `id`
....
}
Query Parameters:
**Query parameters:**
- **size** – 1/True/true or 0/False/false, return container size information. Default is `false`.
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -748,11 +748,11 @@ supported on Windows.
],
}
Query Parameters:
**Query parameters:**
- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef`
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -780,7 +780,7 @@ Get `stdout` and `stderr` logs from the container ``id``
{{ STREAM }}
Query Parameters:
**Query parameters:**
- **details** - 1/True/true or 0/False/flase, Show extra details provided to logs. Default `false`.
- **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
@ -792,7 +792,7 @@ Query Parameters:
every log line. Default `false`.
- **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
Status Codes:
**Status codes:**
- **101** – no error, hints proxy about hijacking
- **200** – no error, no upgrade header found
@ -835,7 +835,7 @@ Values for `Kind`:
- `1`: Add
- `2`: Delete
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -858,7 +858,7 @@ Export the contents of container `id`
{{ TAR STREAM }}
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -978,11 +978,11 @@ This endpoint returns a live stream of a container's resource usage statistics.
The precpu_stats is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the “cpu_stats” field.
Query Parameters:
**Query parameters:**
- **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -1004,12 +1004,12 @@ Resize the TTY for container with `id`. The unit is number of characters. You m
Content-Length: 0
Content-Type: text/plain; charset=utf-8
Query Parameters:
**Query parameters:**
- **h** – height of `tty` session
- **w** – width
Status Codes:
**Status codes:**
- **200** – no error
- **404** – No such container
@ -1029,13 +1029,13 @@ Start the container `id`
HTTP/1.1 204 No Content
Query Parameters:
**Query parameters:**
- **detachKeys** – Override the key sequence for detaching a
container. Format is a single character `[a-Z]` or `ctrl-<value>`
where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
Status Codes:
**Status codes:**
- **204** – no error
- **304** – container already started
@ -1056,11 +1056,11 @@ Stop the container `id`
HTTP/1.1 204 No Content
Query Parameters:
**Query parameters:**
- **t** – number of seconds to wait before killing the container
Status Codes:
**Status codes:**
- **204** – no error
- **304** – container already stopped
@ -1081,11 +1081,11 @@ Restart the container `id`
HTTP/1.1 204 No Content
Query Parameters:
**Query parameters:**
- **t** – number of seconds to wait before killing the container
Status Codes:
**Status codes:**
- **204** – no error
- **404** – no such container
@ -1110,7 +1110,7 @@ Query Parameters
- **signal** - Signal to send to the container: integer or string like `SIGINT`.
When not set, `SIGKILL` is assumed and the call waits for the container to exit.
Status Codes:
**Status codes:**
- **204** – no error
- **404** – no such container
@ -1153,7 +1153,7 @@ Update configuration of one or more containers.
"Warnings": []
}
Status Codes:
**Status codes:**
- **200** – no error
- **400** – bad parameter
@ -1174,11 +1174,11 @@ Rename the container `id` to a `new_name`
HTTP/1.1 204 No Content
Query Parameters:
**Query parameters:**
- **name** – new name for the container
Status Codes:
**Status codes:**
- **204** – no error
- **404** – no such container
@ -1199,7 +1199,7 @@ Pause the container `id`
HTTP/1.1 204 No Content
Status Codes:
**Status codes:**
- **204** – no error
- **404** – no such container
@ -1219,7 +1219,7 @@ Unpause the container `id`
HTTP/1.1 204 No Content
Status Codes:
**Status codes:**
- **204** – no error
- **404** – no such container
@ -1244,7 +1244,7 @@ Attach to the container `id`
{{ STREAM }}
Query Parameters:
**Query parameters:**
- **detachKeys** – Override the key sequence for detaching a
container. Format is a single character `[a-Z]` or `ctrl-<value>`
@ -1259,7 +1259,7 @@ Query Parameters:
- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
`stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
Status Codes:
**Status codes:**
- **101** – no error, hints proxy about hijacking
- **200** – no error, no upgrade header found
@ -1327,7 +1327,7 @@ Implements websocket protocol handshake according to [RFC 6455](http://tools.iet
{{ STREAM }}
Query Parameters:
**Query parameters:**
- **detachKeys** – Override the key sequence for detaching a
container. Format is a single character `[a-Z]` or `ctrl-<value>`
@ -1342,7 +1342,7 @@ Query Parameters:
- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
`stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
Status Codes:
**Status codes:**
- **200** – no error
- **400** – bad parameter
@ -1366,7 +1366,7 @@ Block until container `id` stops, then returns the exit code
{"StatusCode": 0}
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such container
@ -1386,14 +1386,14 @@ Remove the container `id` from the filesystem
HTTP/1.1 204 No Content
Query Parameters:
**Query parameters:**
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default `false`.
- **force** - 1/True/true or 0/False/false, Kill then remove the container.
Default `false`.
Status Codes:
**Status codes:**
- **204** – no error
- **400** – bad parameter
@ -1413,7 +1413,7 @@ following section.
Get a tar archive of a resource in the filesystem of container `id`.
Query Parameters:
**Query parameters:**
- **path** - resource in the container's filesystem to archive. Required.
@ -1424,9 +1424,9 @@ Query Parameters:
indicates that only the contents of the **path** directory should be
copied. A symlink is always resolved to its target.
**Note**: It is not possible to copy certain system files such as resources
under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
container.
> **Note**: It is not possible to copy certain system files such as resources
> under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
> container.
**Example request**:
@ -1445,18 +1445,20 @@ base64-encoded JSON object containing some filesystem header information about
the archived resource. The above example value would decode to the following
JSON object (whitespace added for readability):
{
```json
{
"name": "root",
"size": 4096,
"mode": 2147484096,
"mtime": "2014-02-27T20:51:23Z",
"linkTarget": ""
}
}
```
A `HEAD` request can also be made to this endpoint if only this information is
desired.
Status Codes:
**Status codes:**
- **200** - success, returns archive of copied resource
- **400** - client error, bad parameter, details in JSON response body, one of:
@ -1475,7 +1477,7 @@ Status Codes:
Upload a tar archive to be extracted to a path in the filesystem of container
`id`.
Query Parameters:
**Query parameters:**
- **path** - path to a directory in the container
to extract the archive's contents into. Required.
@ -1497,7 +1499,7 @@ Query Parameters:
HTTP/1.1 200 OK
Status Codes:
**Status codes:**
- **200** – the content was extracted successfully
- **400** - client error, bad parameter, details in JSON response body, one of:
@ -1599,7 +1601,7 @@ digest. You can reference this digest using the value:
See the `docker run` and `docker build` commands for examples of digest and tag
references on the command line.
Query Parameters:
**Query parameters:**
- **all** – 1/True/true or 0/False/false, default false
- **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
@ -1645,7 +1647,7 @@ command*](../../reference/builder.md#dockerbuilder)).
The build is canceled if the client drops the connection by quitting
or being killed.
Query Parameters:
**Query parameters:**
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
@ -1700,7 +1702,7 @@ Query Parameters:
be specified with both a "https://" prefix and a "/v1/" suffix even
though Docker will prefer to use the v2 registry API.
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -1729,7 +1731,7 @@ When using this endpoint to pull an image from the registry, the
`X-Registry-Auth` header can be used to include
a base64-encoded AuthConfig object.
Query Parameters:
**Query parameters:**
- **fromImage** – Name of the image to pull. The name may include a tag or
digest. This parameter may only be used when pulling an image.
@ -1763,7 +1765,7 @@ Query Parameters:
}
```
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -1882,7 +1884,7 @@ Return low-level information on the image `name`
}
}
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such image
@ -1936,7 +1938,7 @@ Return the history of the image `name`
}
]
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such image
@ -1973,7 +1975,7 @@ The push is cancelled if the HTTP connection is closed.
POST /images/registry.acme.com:5000/test/push HTTP/1.1
Query Parameters:
**Query parameters:**
- **tag** – The tag to associate with the image on the registry. This is optional.
@ -1998,7 +2000,7 @@ Request Headers:
}
```
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such image
@ -2018,12 +2020,12 @@ Tag the image `name` into a repository
HTTP/1.1 201 Created
Query Parameters:
**Query parameters:**
- **repo** – The repository to tag in
- **tag** - The new tag name
Status Codes:
**Status codes:**
- **201** – no error
- **400** – bad parameter
@ -2052,12 +2054,12 @@ Remove the image `name` from the filesystem
{"Deleted": "53b4f83ac9"}
]
Query Parameters:
**Query parameters:**
- **force** – 1/True/true or 0/False/false, default false
- **noprune** – 1/True/true or 0/False/false, default false
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such image
@ -2108,7 +2110,7 @@ Search for an image on [Docker Hub](https://hub.docker.com).
...
]
Query Parameters:
**Query parameters:**
- **term** – term to search
- **limit** – maximum returned search results
@ -2117,7 +2119,7 @@ Query Parameters:
- `is-automated=(true|false)`
- `is-official=(true|false)`
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2151,7 +2153,7 @@ if available, for accessing the registry without password.
"IdentityToken": "9cbaf023786cd7..."
}
Status Codes:
**Status codes:**
- **200** – no error
- **204** – no error
@ -2246,7 +2248,7 @@ Display system-wide information
"SystemTime": "2015-03-10T11:11:23.730591467-07:00"
}
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2278,7 +2280,7 @@ Show the docker version information
"Experimental": true
}
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2300,7 +2302,7 @@ Ping the docker server
OK
Status Codes:
**Status codes:**
- **200** - no error
- **500** - server error
@ -2356,11 +2358,11 @@ Create a new image from a container's changes
{"Id": "596069db4bf5"}
Json Parameters:
**JSON parameters:**
- **config** - the container's configuration
Query Parameters:
**Query parameters:**
- **container** – source container
- **repo** – repository
@ -2371,7 +2373,7 @@ Query Parameters:
- **pause** – 1/True/true or 0/False/false, whether to pause the container before committing
- **changes** – Dockerfile instructions to apply while committing
Status Codes:
**Status codes:**
- **201** – no error
- **404** – no such container
@ -2563,7 +2565,7 @@ Docker daemon report the following event:
"timeNano": 1461943105338056026
}
Query Parameters:
**Query parameters:**
- **since** – Timestamp used for polling
- **until** – Timestamp used for polling
@ -2577,7 +2579,7 @@ Query Parameters:
- `network=<string>`; -- network to filter
- `daemon=<string>`; -- daemon name or id to filter
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2607,12 +2609,12 @@ See the [image tarball format](#image-tarball-format) for more details.
Binary data stream
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
### Get a tarball containing all images.
### Get a tarball containing all images
`GET /images/get`
@ -2636,7 +2638,7 @@ See the [image tarball format](#image-tarball-format) for more details.
Binary data stream
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2658,7 +2660,7 @@ See the [image tarball format](#image-tarball-format) for more details.
HTTP/1.1 200 OK
Status Codes:
**Status codes:**
- **200** – no error
- **500** – server error
@ -2716,7 +2718,7 @@ Sets up an exec instance in a running container `id`
"Warnings":[]
}
Json Parameters:
**JSON parameters:**
- **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
- **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
@ -2728,7 +2730,7 @@ Json Parameters:
- **Cmd** - Command to run specified as a string or an array of strings.
Status Codes:
**Status codes:**
- **201** – no error
- **404** – no such container
@ -2760,12 +2762,12 @@ interactive session with the `exec` command.
{{ STREAM }}
Json Parameters:
**JSON parameters:**
- **Detach** - Detach from the `exec` command.
- **Tty** - Boolean value to allocate a pseudo-TTY.
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such exec instance
@ -2791,12 +2793,12 @@ This API is valid only if `tty` was specified as part of creating and starting t
HTTP/1.1 201 Created
Content-Type: text/plain
Query Parameters:
**Query parameters:**
- **h** – height of `tty` session
- **w** – width
Status Codes:
**Status codes:**
- **201** – no error
- **404** – no such exec instance
@ -2838,7 +2840,7 @@ Return low-level information about the `exec` command `id`.
"Running": false
}
Status Codes:
**Status codes:**
- **200** – no error
- **404** – no such exec instance
@ -2870,14 +2872,14 @@ Status Codes:
"Warnings": []
}
Query Parameters:
**Query parameters:**
- **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:
- `name=<volume-name>` Matches all or part of a volume name.
- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are "dangling" (not in use by a container). When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches all or part of a volume driver name.
Status Codes:
**Status codes:**
- **200** - no error
- **500** - server error
@ -2917,12 +2919,12 @@ Create a volume
},
}
Status Codes:
**Status codes:**
- **201** - no error
- **500** - server error
JSON Parameters:
**JSON parameters:**
- **Name** - The new volume's name. If not specified, Docker generates a name.
- **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
@ -2955,7 +2957,7 @@ Return low-level information on the volume `name`
}
}
Status Codes:
**Status codes:**
- **200** - no error
- **404** - no such volume
@ -3062,7 +3064,7 @@ Content-Type: application/json
]
```
Query Parameters:
**Query parameters:**
- **filters** - JSON encoded network list filter. The filter value is one of:
- `driver=<driver-name>` Matches a network's driver.
@ -3071,7 +3073,7 @@ Query Parameters:
- `name=<network-name>` Matches all or part of a network name.
- `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks.
Status Codes:
**Status codes:**
- **200** - no error
- **500** - server error
@ -3133,7 +3135,7 @@ Content-Type: application/json
}
```
Status Codes:
**Status codes:**
- **200** - no error
- **404** - network not found
@ -3199,13 +3201,13 @@ Content-Type: application/json
}
```
Status Codes:
**Status codes:**
- **201** - no error
- **404** - plugin not found
- **500** - server error
JSON Parameters:
**JSON parameters:**
- **Name** - The new network's name. this is a mandatory field
- **CheckDuplicate** - Requests daemon to check for networks with same name
@ -3243,13 +3245,13 @@ Content-Type: application/json
HTTP/1.1 200 OK
Status Codes:
**Status codes:**
- **200** - no error
- **404** - network or container is not found
- **500** - Internal Server Error
JSON Parameters:
**JSON parameters:**
- **container** - container-id/name to be connected to the network
@ -3275,13 +3277,13 @@ Content-Type: application/json
HTTP/1.1 200 OK
Status Codes:
**Status codes:**
- **200** - no error
- **404** - network or container not found
- **500** - Internal Server Error
JSON Parameters:
**JSON parameters:**
- **Container** - container-id/name to be disconnected from a network
- **Force** - Force the container to disconnect from a network