mobi/moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2026-01-06 07:21:23 +03:00
Code Activity

move the documentation to markdown

Browse Source 
Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: )
This commit is contained in:
Sven Dowideit
2014-04-15 06:01:25 +00:00
parent 80f6b01132
commit 936a03bfdd
87 changed files with 34848 additions and 347 deletions
Download Patch File Download Diff File Expand all files Collapse all files

998
docs/sources/reference/api/archive/docker_remote_api_v1.0.md Normal file
View File

@@ -0,0 +1,998 @@
page_title: Remote API v1.0
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.0](#id1)
Table of Contents
- [Docker Remote API v1.0](#docker-remote-api-v1-0)
- [1. Brief introduction](#brief-introduction)
- [2. Endpoints](#endpoints)
- [2.1 Containers](#containers)
- [List containers](#list-containers)
- [Create a container](#create-a-container)
- [Inspect a container](#inspect-a-container)
- [Inspect changes on a container’s
filesystem](#inspect-changes-on-a-container-s-filesystem)
- [Export a container](#export-a-container)
- [Start a container](#start-a-container)
- [Stop a container](#stop-a-container)
- [Restart a container](#restart-a-container)
- [Kill a container](#kill-a-container)
- [Attach to a container](#attach-to-a-container)
- [Wait a container](#wait-a-container)
- [Remove a container](#remove-a-container)
- [2.2 Images](#images)
- [List Images](#list-images)
- [Create an image](#create-an-image)
- [Insert a file in an image](#insert-a-file-in-an-image)
- [Inspect an image](#inspect-an-image)
- [Get the history of an
image](#get-the-history-of-an-image)
- [Push an image on the
registry](#push-an-image-on-the-registry)
- [Tag an image into a
repository](#tag-an-image-into-a-repository)
- [Remove an image](#remove-an-image)
- [Search images](#search-images)
- [2.3 Misc](#misc)
- [Build an image from Dockerfile via
stdin](#build-an-image-from-dockerfile-via-stdin)
- [Get default username and
email](#get-default-username-and-email)
- [Check auth configuration and store
it](#check-auth-configuration-and-store-it)
- [Display system-wide
information](#display-system-wide-information)
- [Show the docker version
information](#show-the-docker-version-information)
- [Create a new image from a container’s
changes](#create-a-new-image-from-a-container-s-changes)
- [3. Going further](#going-further)
- [3.1 Inside ‘docker run’](#inside-docker-run)
- [3.2 Hijacking](#hijacking)
## [1. Brief introduction](#id2)
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
### [2.1 Containers](#id4)
#### [List containers](#id5)
`GET /containers/json`
: List containers
**Example request**:
GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Id": "8dfafdbc3a40",
"Image": "ubuntu:latest",
"Command": "echo 1",
"Created": 1367854155,
"Status": "Exit 0"
},
{
"Id": "9cd87474be90",
"Image": "ubuntu:latest",
"Command": "echo 222222",
"Created": 1367854155,
"Status": "Exit 0"
},
{
"Id": "3176a2479c92",
"Image": "centos:latest",
"Command": "echo 3333333333333333",
"Created": 1367854154,
"Status": "Exit 0"
},
{
"Id": "4cb07b47f9fb",
"Image": "fedora:latest",
"Command": "echo 444444444444444444444444444444444",
"Created": 1367854152,
"Status": "Exit 0"
}
]
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
- **limit** – Show `limit` last created
containers, include non-running ones.
- **since** – Show only containers created since Id, include
non-running ones.
- **before** – Show only containers created before Id, include
non-running ones.
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
`POST /containers/create`
: Create a container
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
{
"Hostname":"",
"User":"",
"Memory":0,
"MemorySwap":0,
"AttachStdin":false,
"AttachStdout":true,
"AttachStderr":true,
"PortSpecs":null,
"Tty":false,
"OpenStdin":false,
"StdinOnce":false,
"Env":null,
"Cmd":[
"date"
],
"Dns":null,
"Image":"ubuntu",
"Volumes":{},
"VolumesFrom":""
}
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/json
{
"Id":"e90e34656806"
"Warnings":[]
}
Json Parameters:
 
- **config** – the container’s configuration
Status Codes:
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
**Example request**:
GET /containers/4fa6e0f0c678/json HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
"Created": "2013-05-07T14:51:42.041847+02:00",
"Path": "date",
"Args": [],
"Config": {
"Hostname": "4fa6e0f0c678",
"User": "",
"Memory": 0,
"MemorySwap": 0,
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"PortSpecs": null,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": null,
"Cmd": [
"date"
],
"Dns": null,
"Image": "ubuntu",
"Volumes": {},
"VolumesFrom": ""
},
"State": {
"Running": false,
"Pid": 0,
"ExitCode": 0,
"StartedAt": "2013-05-07T14:51:42.087658+02:01360",
"Ghost": false
},
"Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"NetworkSettings": {
"IpAddress": "",
"IpPrefixLen": 0,
"Gateway": "",
"Bridge": "",
"PortMapping": null
},
"SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
"ResolvConfPath": "/etc/resolv.conf",
"Volumes": {}
}
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id8)
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
**Example request**:
GET /containers/4fa6e0f0c678/changes HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Path":"/dev",
"Kind":0
},
{
"Path":"/dev/kmsg",
"Kind":1
},
{
"Path":"/test",
"Kind":1
}
]
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
#### [Export a container](#id9)
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
**Example request**:
GET /containers/4fa6e0f0c678/export HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/octet-stream
{{ STREAM }}
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
#### [Start a container](#id10)
`POST /containers/`(*id*)`/start`
: Start the container `id`
**Example request**:
POST /containers/e90e34656806/start HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
#### [Stop a container](#id11)
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
**Example request**:
POST /containers/e90e34656806/stop?t=5 HTTP/1.1
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
#### [Restart a container](#id12)
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
**Example request**:
POST /containers/e90e34656806/restart?t=5 HTTP/1.1
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
#### [Kill a container](#id13)
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
**Example request**:
POST /containers/e90e34656806/kill HTTP/1.1
**Example response**:
HTTP/1.1 204 OK
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id14)
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
**Example request**:
POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
 
- **logs** – 1/True/true or 0/False/false, return logs. Default
false
- **stream** – 1/True/true or 0/False/false, return stream.
Default false
- **stdin** – 1/True/true or 0/False/false, if stream=true, attach
to stdin. Default false
- **stdout** – 1/True/true or 0/False/false, if logs=true, return
stdout log, if stream=true, attach to stdout. Default false
- **stderr** – 1/True/true or 0/False/false, if logs=true, return
stderr log, if stream=true, attach to stderr. Default false
Status Codes:
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
#### [Wait a container](#id15)
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
**Example request**:
POST /containers/16253994b7c4/wait HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{"StatusCode":0}
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
#### [Remove a container](#id16)
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
**Example request**:
DELETE /containers/16253994b7c4?v=1 HTTP/1.1
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
 
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default false
Status Codes:
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
### [2.2 Images](#id17)
#### [List Images](#id18)
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
**Example request**:
GET /images/json?all=0 HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Repository":"ubuntu",
"Tag":"precise",
"Id":"b750fe79269d",
"Created":1364102658
},
{
"Repository":"ubuntu",
"Tag":"12.04",
"Id":"b750fe79269d",
"Created":1364102658
}
]
**Example request**:
GET /images/viz HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: text/plain
digraph docker {
"d82cbacda43a" -> "074be284591f"
"1496068ca813" -> "08306dc45919"
"08306dc45919" -> "0e7893146ac2"
"b750fe79269d" -> "1496068ca813"
base -> "27cf78414709" [style=invis]
"f71189fff3de" -> "9a33b36209ed"
"27cf78414709" -> "b750fe79269d"
"0e7893146ac2" -> "d6434d954665"
"d6434d954665" -> "d82cbacda43a"
base -> "e9aa60c60128" [style=invis]
"074be284591f" -> "f71189fff3de"
"b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
"e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
"9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
base [style=invisible]
}
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id19)
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
**Example request**:
POST /images/create?fromImage=ubuntu HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
 
- **fromImage** – name of the image to pull
- **fromSrc** – source to import, - means stdin
- **repo** – repository
- **tag** – tag
- **registry** – the registry to pull from
Status Codes:
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id20)
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
**Example request**:
POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
{{ STREAM }}
Status Codes:
- **200** – no error
- **500** – server error
#### [Inspect an image](#id21)
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
**Example request**:
GET /images/centos/json HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"parent":"27cf784147099545",
"created":"2013-03-23T22:24:18.818426-07:00",
"container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
"container_config":
{
"Hostname":"",
"User":"",
"Memory":0,
"MemorySwap":0,
"AttachStdin":false,
"AttachStdout":false,
"AttachStderr":false,
"PortSpecs":null,
"Tty":true,
"OpenStdin":true,
"StdinOnce":false,
"Env":null,
"Cmd": ["/bin/bash"]
,"Dns":null,
"Image":"centos",
"Volumes":null,
"VolumesFrom":""
}
}
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id22)
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
**Example request**:
GET /images/fedora/history HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Id":"b750fe79269d",
"Created":1364102658,
"CreatedBy":"/bin/bash"
},
{
"Id":"27cf78414709",
"Created":1364068391,
"CreatedBy":""
}
]
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id23)
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
> **Example request**:
>
> POST /images/test/push HTTP/1.1
>
> **Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
 
- **registry** – the registry you wan to push, optional
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id24)
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
**Example request**:
POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
**Example response**:
HTTP/1.1 201 OK
Query Parameters:
 
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
Status Codes:
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **500** – server error
#### [Remove an image](#id25)
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
**Example request**:
DELETE /images/test HTTP/1.1
**Example response**:
HTTP/1.1 204 OK
Status Codes:
- **204** – no error
- **404** – no such image
- **500** – server error
#### [Search images](#id26)
`GET /images/search`
: Search for an image in the docker index
**Example request**:
GET /images/search?term=sshd HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Name":"cespare/sshd",
"Description":""
},
{
"Name":"johnfuller/sshd",
"Description":""
},
{
"Name":"dhrp/mongodb-sshd",
"Description":""
}
]
:query term: term to search
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id27)
#### [Build an image from Dockerfile via stdin](#id28)
`POST /build`
: Build an image from Dockerfile via stdin
**Example request**:
POST /build HTTP/1.1
{{ STREAM }}
**Example response**:
HTTP/1.1 200 OK
{{ STREAM }}
Query Parameters:
 
- **t** – repository name to be applied to the resulting image in
case of success
Status Codes:
- **200** – no error
- **500** – server error
#### [Get default username and email](#id29)
`GET /auth`
: Get the default username and email
**Example request**:
GET /auth HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"username":"hannibal",
"email":"hannibal@a-team.com"
}
Status Codes:
- **200** – no error
- **500** – server error
#### [Check auth configuration and store it](#id30)
`POST /auth`
: Get the default username and email
**Example request**:
POST /auth HTTP/1.1
Content-Type: application/json
{
"username":"hannibal",
"password:"xxxx",
"email":"hannibal@a-team.com"
}
**Example response**:
HTTP/1.1 200 OK
Status Codes:
- **200** – no error
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id31)
`GET /info`
: Display system-wide information
**Example request**:
GET /info HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Containers":11,
"Images":16,
"Debug":false,
"NFd": 11,
"NGoroutines":21,
"MemoryLimit":true,
"SwapLimit":false
}
Status Codes:
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id32)
`GET /version`
: Show the docker version information
**Example request**:
GET /version HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Version":"0.2.2",
"GitCommit":"5a2a5cc+CHANGES",
"GoVersion":"go1.0.3"
}
Status Codes:
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id33)
`POST /commit`
: Create a new image from a container’s changes
>
> **Example request**:
POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
Content-Type: application/json
{
"Cmd": ["cat", "/world"],
"PortSpecs":["22"]
}
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/vnd.docker.raw-stream
{"Id":"596069db4bf5"}
Query Parameters:
 
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
Status Codes:
- **201** – no error
- **404** – no such container
- **500** – server error
## [3. Going further](#id34)
### [3.1 Inside ‘docker run’](#id35)
Here are the steps of ‘docker run’ :
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
### [3.2 Hijacking](#id36)
In this first version of the API, some of the endpoints, like /attach,
/pull or /push uses hijacking to transport stdin, stdout and stderr on
the same socket. This might change in the future.