kotovalexarian-likes-github
/
moby--moby
mirror of https://github.com/moby/moby.git
1
0
Fork 0
Code Releases Activity

Reformat the API docs so I can read them 

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@docker.com> (github: SvenDowideit)
This commit is contained in:
Sven Dowideit 2014-09-09 15:00:23 +10:00
parent bb8ea1fdc1
commit f36dfbdcaf
20 changed files with 4458 additions and 4438 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
docs/sources/reference/api/docker-io_api.md
View File

@ -4,23 +4,21 @@ page_keywords: API, Docker, index, REST, documentation, Docker Hub, registry
# Docker Hub API
## Introduction
- This is the REST API for [Docker Hub](https://hub.docker.com).
- Authorization is done with basic auth over SSL
- Not all commands require authentication, only those noted as such.
## Repository
# Repositories
### Repositories
## User Repository
#### User Repo
### Create a user repository
`PUT /v1/repositories/(namespace)/(repo_name)/`
Create a user repository with the given `namespace` and `repo_name`.
**Example Request**:
**Example Request**:
PUT /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
@ -31,12 +29,12 @@ Create a user repository with the given `namespace` and `repo_name`.
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
Parameters:
Parameters:
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -47,18 +45,20 @@ Create a user repository with the given `namespace` and `repo_name`.
""
Status Codes:
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
### Delete a user repository
`DELETE /v1/repositories/(namespace)/(repo_name)/`
Delete a user repository with the given `namespace` and `repo_name`.
**Example Request**:
**Example Request**:
DELETE /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
@ -69,12 +69,12 @@ Delete a user repository with the given `namespace` and `repo_name`.
""
Parameters:
Parameters:
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 202
Vary: Accept
@ -85,25 +85,27 @@ Delete a user repository with the given `namespace` and `repo_name`.
""
Status Codes:
Status Codes:
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
#### Library Repo
## Library Repository
### Create a library repository
`PUT /v1/repositories/(repo_name)/`
Create a library repository with the given `repo_name`.
This is a restricted feature only available to docker admins.
When namespace is missing, it is assumed to be `library`
> When namespace is missing, it is assumed to be `library`
**Example Request**:
**Example Request**:
PUT /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
@ -114,11 +116,11 @@ This is a restricted feature only available to docker admins.
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
Parameters:
Parameters:
- **repo_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -129,22 +131,24 @@ This is a restricted feature only available to docker admins.
""
Status Codes:
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
### Delete a library repository
`DELETE /v1/repositories/(repo_name)/`
Delete a library repository with the given `repo_name`.
This is a restricted feature only available to docker admins.
When namespace is missing, it is assumed to be `library`
> When namespace is missing, it is assumed to be `library`
**Example Request**:
**Example Request**:
DELETE /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
@ -155,11 +159,11 @@ This is a restricted feature only available to docker admins.
""
Parameters:
Parameters:
- **repo_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 202
Vary: Accept
@ -170,23 +174,25 @@ This is a restricted feature only available to docker admins.
""
Status Codes:
Status Codes:
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
### Repository Images
# Repository Images
#### User Repo Images
## User Repository Images
### Update user repository images
`PUT /v1/repositories/(namespace)/(repo_name)/images`
Update the images for a user repo.
**Example Request**:
**Example Request**:
PUT /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
@ -197,12 +203,12 @@ Update the images for a user repo.
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
Parameters:
Parameters:
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 204
Vary: Accept
@ -210,29 +216,31 @@ Update the images for a user repo.
""
Status Codes:
Status Codes:
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
### List user repository images
`GET /v1/repositories/(namespace)/(repo_name)/images`
Get the images for a user repo.
**Example Request**:
**Example Request**:
GET /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Parameters:
Parameters:
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -243,18 +251,20 @@ Get the images for a user repo.
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
Status Codes:
Status Codes:
- **200** – OK
- **404** – Not found
- **200** – OK
- **404** – Not found
#### Library Repo Images
## Library Repository Images
### Update library repository images
`PUT /v1/repositories/(repo_name)/images`
Update the images for a library repo.
**Example Request**:
**Example Request**:
PUT /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
@ -265,11 +275,11 @@ Update the images for a library repo.
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
Parameters:
Parameters:
- **repo_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 204
Vary: Accept
@ -277,28 +287,30 @@ Update the images for a library repo.
""
Status Codes:
Status Codes:
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
### List library repository images
`GET /v1/repositories/(repo_name)/images`
Get the images for a library repo.
**Example Request**:
**Example Request**:
GET /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Parameters:
Parameters:
- **repo_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -309,31 +321,33 @@ Get the images for a library repo.
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
Status Codes:
Status Codes:
- **200** – OK
- **404** – Not found
- **200** – OK
- **404** – Not found
### Repository Authorization
# Repository Authorization
#### Library Repo
## Library Repository
### Authorize a toke for a library
`PUT /v1/repositories/(repo_name)/auth`
Authorize a token for a library repo
**Example Request**:
**Example Request**:
PUT /v1/repositories/foobar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="library/foobar",access=write
Parameters:
Parameters:
- **repo_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -341,31 +355,33 @@ Authorize a token for a library repo
"OK"
Status Codes:
Status Codes:
- **200** – OK
- **403** – Permission denied
- **404** – Not found
- **200** – OK
- **403** – Permission denied
- **404** – Not found
#### User Repo
## User Repository
### Authorize a toke for a user repository
`PUT /v1/repositories/(namespace)/(repo_name)/auth`
Authorize a token for a user repo
**Example Request**:
**Example Request**:
PUT /v1/repositories/foo/bar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="foo/bar",access=write
Parameters:
Parameters:
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
- **namespace** – the namespace for the repo
- **repo_name** – the name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -373,28 +389,28 @@ Authorize a token for a user repo
"OK"
Status Codes:
Status Codes:
- **200** – OK
- **403** – Permission denied
- **404** – Not found
- **200** – OK
- **403** – Permission denied
- **404** – Not found
### Users
## Users
#### User Login
### User Login
`GET /v1/users`
If you want to check your login, you can try this endpoint
**Example Request**:
**Example Request**:
GET /v1/users HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Basic akmklmasadalkm==
**Example Response**:
**Example Response**:
HTTP/1.1 200 OK
Vary: Accept
@ -402,19 +418,19 @@ If you want to check your login, you can try this endpoint
OK
Status Codes:
Status Codes:
- **200** – no error
- **401** – Unauthorized
- **403** – Account is not Active
- **200** – no error
- **401** – Unauthorized
- **403** – Account is not Active
#### User Register
### User Register
`POST /v1/users`
Registering a new account.
**Example request**:
**Example request**:
POST /v1/users HTTP/1.1
Host: index.docker.io
@ -425,16 +441,14 @@ Registering a new account.
"password": "toto42",
"username": "foobar"}
Json Parameters:
Json Parameters:
 
- **email** – valid email address, that needs to be confirmed
- **username** – min 4 character, max 30 characters, must match
- **email** – valid email address, that needs to be confirmed
- **username** – min 4 character, max 30 characters, must match
the regular expression [a-z0-9_].
- **password** – min 5 characters
- **password** – min 5 characters
**Example Response**:
**Example Response**:
HTTP/1.1 201 OK
Vary: Accept
@ -442,25 +456,24 @@ Registering a new account.
"User Created"
Status Codes:
Status Codes:
- **201** – User Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **201** – User Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
#### Update User
### Update User
`PUT /v1/users/(username)/`
Change a password or email address for given user. If you pass in an
email, it will add it to your account, it will not remove the old
one. Passwords will be updated.
email, it will add it to your account, it will not remove the old
one. Passwords will be updated.
It is up to the client to verify that that password that is sent is
the one that they want. Common approach is to have them type it
twice.
It is up to the client to verify that that password that is sent is
the one that they want. Common approach is to have them type it
twice.
**Example Request**:
**Example Request**:
PUT /v1/users/fakeuser/ HTTP/1.1
Host: index.docker.io
@ -471,11 +484,11 @@ Change a password or email address for given user. If you pass in an
{"email": "sam@docker.com",
"password": "toto42"}
Parameters:
Parameters:
- **username** – username for the person you want to update
- **username** – username for the person you want to update
**Example Response**:
**Example Response**:
HTTP/1.1 204
Vary: Accept
@ -483,20 +496,18 @@ Change a password or email address for given user. If you pass in an
""
Status Codes:
Status Codes:
- **204** – User Updated
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **404** – User not found
- **204** – User Updated
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **404** – User not found
## Search
If you need to search the index, this is the endpoint you would use.
### Search
`GET /v1/search`
Search the Index given a search term. It accepts
@ -504,13 +515,13 @@ Search the Index given a search term. It accepts
[GET](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3)
only.
**Example request**:
**Example request**:
GET /v1/search?q=search_term HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Vary: Accept
@ -525,11 +536,11 @@ Search the Index given a search term. It accepts
]
}
Query Parameters:
Query Parameters:
- **q** – what you want to search for
- **q** – what you want to search for
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error

162
docs/sources/reference/api/docker_io_accounts_api.md
View File

@ -4,43 +4,39 @@ page_keywords: API, Docker, accounts, REST, documentation
# docker.io Accounts API
## 1. Endpoints
### 1.1 Get a single user
## Get a single user
`GET /api/v1.1/users/:username/`
Get profile info for the specified user.
Parameters:
Parameters:
- **username** – username of the user whose profile info is being
- **username** – username of the user whose profile info is being
requested.
Request Headers:
Request Headers:
 
- **Authorization** – required authentication credentials of
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
Status Codes:
Status Codes:
- **200** – success, user data returned.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
- **200** – success, user data returned.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`profile_read` scope.
- **404** – the specified username does not exist.
- **404** – the specified username does not exist.
**Example request**:
**Example request**:
GET /api/v1.1/users/janedoe/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -60,48 +56,44 @@ Get profile info for the specified user.
"is_active": true
}
### 1.2 Update a single user
## Update a single user
`PATCH /api/v1.1/users/:username/`
Update profile info for the specified user.
Parameters:
Parameters:
- **username** – username of the user whose profile info is being
- **username** – username of the user whose profile info is being
updated.
Json Parameters:
Json Parameters:
 
- **full_name** (*string*) – (optional) the new name of the user.
- **location** (*string*) – (optional) the new location.
- **company** (*string*) – (optional) the new company of the user.
- **profile_url** (*string*) – (optional) the new profile url.
- **gravatar_email** (*string*) – (optional) the new Gravatar
- **full_name** (*string*) – (optional) the new name of the user.
- **location** (*string*) – (optional) the new location.
- **company** (*string*) – (optional) the new company of the user.
- **profile_url** (*string*) – (optional) the new profile url.
- **gravatar_email** (*string*) – (optional) the new Gravatar
email address.
Request Headers:
Request Headers:
 
- **Authorization** – required authentication credentials of
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
Status Codes:
- **200** – success, user data updated.
- **400** – post data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
- **200** – success, user data updated.
- **400** – post data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being updated, OAuth access tokens must have
`profile_write` scope.
- **404** – the specified username does not exist.
- **404** – the specified username does not exist.
**Example request**:
**Example request**:
PATCH /api/v1.1/users/janedoe/ HTTP/1.1
Host: www.docker.io
@ -114,7 +106,7 @@ Update profile info for the specified user.
"company": "Retired",
}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -134,41 +126,39 @@ Update profile info for the specified user.
"is_active": true
}
### 1.3 List email addresses for a user
## List email addresses for a user
`GET /api/v1.1/users/:username/emails/`
List email info for the specified user.
Parameters:
Parameters:
- **username** – username of the user whose profile info is being
- **username** – username of the user whose profile info is being
updated.
Request Headers:
Request Headers:
 
- **Authorization** – required authentication credentials of
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token
Status Codes:
Status Codes:
- **200** – success, user data updated.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
- **200** – success, user data updated.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_read` scope.
- **404** – the specified username does not exist.
- **404** – the specified username does not exist.
**Example request**:
**Example request**:
GET /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -181,7 +171,7 @@ List email info for the specified user.
}
]
### 1.4 Add email address for a user
## Add email address for a user
`POST /api/v1.1/users/:username/emails/`
@ -189,32 +179,28 @@ Add a new email address to the specified user's account. The email
address must be verified separately, a confirmation email is not
automatically sent.
Json Parameters:
Json Parameters:
 
- **email** (*string*) – email address to be added.
- **email** (*string*) – email address to be added.
Request Headers:
Request Headers:
 
- **Authorization** – required authentication credentials of
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
Status Codes:
- **201** – success, new email added.
- **400** – data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
- **201** – success, new email added.
- **400** – data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_write` scope.
- **404** – the specified username does not exist.
- **404** – the specified username does not exist.
**Example request**:
**Example request**:
POST /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
@ -226,7 +212,7 @@ automatically sent.
"email": "jane.doe+other@example.com"
}
**Example response**:
**Example response**:
HTTP/1.1 201 Created
Content-Type: application/json
@ -237,40 +223,36 @@ automatically sent.
"primary": false
}
### 1.5 Delete email address for a user
## Delete email address for a user
`DELETE /api/v1.1/users/:username/emails/`
Delete an email address from the specified user's account. You
cannot delete a user's primary email address.
Json Parameters:
Json Parameters:
 
- **email** (*string*) – email address to be deleted.
- **email** (*string*) – email address to be deleted.
Request Headers:
Request Headers:
 
- **Authorization** – required authentication credentials of
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
Status Codes:
- **204** – success, email address removed.
- **400** – validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
- **204** – success, email address removed.
- **400** – validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_write` scope.
- **404** – the specified username or email address does not
- **404** – the specified username or email address does not
exist.
**Example request**:
**Example request**:
DELETE /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
@ -282,7 +264,7 @@ cannot delete a user's primary email address.
"email": "jane.doe+other@example.com"
}
**Example response**:
**Example response**:
HTTP/1.1 204 NO CONTENT
Content-Length: 0

406
docs/sources/reference/api/docker_remote_api_v1.0.md
View File

@ -22,11 +22,11 @@ page_keywords: API, Docker, rcli, REST, documentation
List containers
**Example request**:
**Example request**:
GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -62,24 +62,24 @@ List containers
}
]
Query Parameters:
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
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
- **limit** – Show `limit` last created
containers, include non-running ones.
- **since** – Show only containers created since Id, include
- **since** – Show only containers created since Id, include
non-running ones.
- **before** – Show only containers created before Id, include
- **before** – Show only containers created before Id, include
non-running ones.
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create a container
@ -87,7 +87,7 @@ List containers
Create a container
**Example request**:
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
@ -114,7 +114,7 @@ Create a container
"VolumesFrom":""
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/json
@ -124,18 +124,18 @@ Create a container
"Warnings":[]
}
Json Parameters:
Json Parameters:
 
- **config** – the container's configuration
- **config** – the container's configuration
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
### Inspect a container
@ -144,11 +144,11 @@ Create a container
Return low-level information on the container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -199,11 +199,11 @@ Return low-level information on the container `id`
"Volumes": {}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Inspect changes on a container's filesystem
@ -211,11 +211,11 @@ Return low-level information on the container `id`
Inspect changes on container `id`'s filesystem
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/changes HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -235,11 +235,11 @@ Inspect changes on container `id`'s filesystem
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Export a container
@ -247,22 +247,22 @@ Inspect changes on container `id`'s filesystem
Export the contents of container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/export HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/octet-stream
{{ TAR STREAM }}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Start a container
@ -270,19 +270,19 @@ Export the contents of container `id`
Start the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/start HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Stop a container
@ -290,25 +290,25 @@ Start the container `id`
Stop the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/stop?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Restart a container
@ -316,25 +316,25 @@ Stop the container `id`
Restart the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/restart?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Kill a container
@ -342,19 +342,19 @@ Restart the container `id`
Kill the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/kill HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Attach to a container
@ -362,38 +362,38 @@ Kill the container `id`
Attach to the container `id`
**Example request**:
**Example request**:
POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **logs** – 1/True/true or 0/False/false, return logs. Default
- **logs** – 1/True/true or 0/False/false, return logs. Defaul
false
- **stream** – 1/True/true or 0/False/false, return stream.
- **stream** – 1/True/true or 0/False/false, return stream.
Default false
- **stdin** – 1/True/true or 0/False/false, if stream=true, attach
- **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** – 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** – 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
- **404** – no such container
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
### Wait a container
@ -401,22 +401,22 @@ Attach to the container `id`
Block until container `id` stops, then returns the exit code
**Example request**:
**Example request**:
POST /containers/16253994b7c4/wait HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{"StatusCode":0}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Remove a container
@ -424,27 +424,27 @@ Block until container `id` stops, then returns the exit code
Remove the container `id` from the filesystem
**Example request**:
**Example request**:
DELETE /containers/16253994b7c4?v=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **v** – 1/True/true or 0/False/false, Remove the volumes
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default false
Status Codes:
Status Codes:
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
## 2.2 Images
@ -454,11 +454,11 @@ Remove the container `id` from the filesystem
List images `format` could be json or viz (json default)
**Example request**:
**Example request**:
GET /images/json?all=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -478,11 +478,11 @@ List images `format` could be json or viz (json default)
}
]
**Example request**:
**Example request**:
GET /images/viz HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: text/plain
@ -505,50 +505,50 @@ List images `format` could be json or viz (json default)
base [style=invisible]
}
Query Parameters:
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create an image
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
Create an image, either by pull it from the registry or by importing i
**Example request**:
**Example request**:
POST /images/create?fromImage=ubuntu HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
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
- **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:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Insert a file in an image
@ -556,27 +556,25 @@ Create an image, either by pull it from the registry or by importing it
Insert a file from `url` in the image `name` at `path`
**Example request**:
**Example request**:
POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
{{ TAR STREAM }}
Query Parameters:
Query Parameters:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Inspect an image
@ -584,11 +582,11 @@ Insert a file from `url` in the image `name` at `path`
Return low-level information on the image `name`
**Example request**:
**Example request**:
GET /images/centos/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -620,11 +618,11 @@ Return low-level information on the image `name`
}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Get the history of an image
@ -632,11 +630,11 @@ Return low-level information on the image `name`
Return the history of the image `name`
**Example request**:
**Example request**:
GET /images/fedora/history HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -654,11 +652,11 @@ Return the history of the image `name`
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Push an image on the registry
@ -677,11 +675,11 @@ Push the image `name` on the registry
{{ STREAM }}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Tag an image into a repository
@ -689,27 +687,27 @@ Push the image `name` on the registry
Tag the image `name` into a repository
**Example request**:
**Example request**:
POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Query Parameters:
Query Parameters:
 
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
Status Codes:
Status Codes:
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **500** – server error
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **500** – server error
### Remove an image
@ -717,19 +715,19 @@ Tag the image `name` into a repository
Remove the image `name` from the filesystem
**Example request**:
**Example request**:
DELETE /images/test HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such image
- **500** – server error
- **204** – no error
- **404** – no such image
- **500** – server error
### Search images
@ -737,11 +735,11 @@ Remove the image `name` from the filesystem
Search for an image on [Docker Hub](https://hub.docker.com)
**Example request**:
**Example request**:
GET /images/search?term=sshd HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -773,29 +771,29 @@ Search for an image on [Docker Hub](https://hub.docker.com)
Build an image from Dockerfile via stdin
**Example request**:
**Example request**:
POST /build HTTP/1.1
{{ TAR STREAM }}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **t** – repository name to be applied to the resulting image in
- **t** – repository name to be applied to the resulting image in
case of success
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Get default username and email
@ -803,11 +801,11 @@ Build an image from Dockerfile via stdin
Get the default username and email
**Example request**:
**Example request**:
GET /auth HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -817,18 +815,18 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Check auth configuration and store it
### Check auth configuration and store i
`POST /auth`
Get the default username and email
**Example request**:
**Example request**:
POST /auth HTTP/1.1
Content-Type: application/json
@ -839,15 +837,15 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **204** – no error
- **500** – server error
- **200** – no error
- **204** – no error
- **500** – server error
### Display system-wide information
@ -855,11 +853,11 @@ Get the default username and email
Display system-wide information
**Example request**:
**Example request**:
GET /info HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -874,10 +872,10 @@ Display system-wide information
"SwapLimit":false
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Show the docker version information
@ -885,11 +883,11 @@ Display system-wide information
Show the docker version information
**Example request**:
**Example request**:
GET /version HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -900,10 +898,10 @@ Show the docker version information
"GoVersion":"go1.0.3"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Create a new image from a container's changes
@ -921,29 +919,29 @@ Create a new image from a container's changes
"PortSpecs":["22"]
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/vnd.docker.raw-stream
{"Id":"596069db4bf5"}
Query Parameters:
Query Parameters:
 
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **500** – server error
- **201** – no error
- **404** – no such container
- **500** – server error
# 3. Going further
@ -954,7 +952,7 @@ 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
- Try to pull i
- Then retry to create the container
- Start the container
@ -970,4 +968,4 @@ Here are the steps of `docker run` :
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.
he same socket. This might change in the future.

408
docs/sources/reference/api/docker_remote_api_v1.1.md
View File

@ -22,11 +22,11 @@ page_keywords: API, Docker, rcli, REST, documentation
List containers
**Example request**:
**Example request**:
GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -62,24 +62,24 @@ List containers
}
]
Query Parameters:
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
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
- **limit** – Show `limit` last created
containers, include non-running ones.
- **since** – Show only containers created since Id, include
- **since** – Show only containers created since Id, include
non-running ones.
- **before** – Show only containers created before Id, include
- **before** – Show only containers created before Id, include
non-running ones.
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create a container
@ -87,7 +87,7 @@ List containers
Create a container
**Example request**:
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
@ -114,7 +114,7 @@ Create a container
"VolumesFrom":""
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/json
@ -124,18 +124,18 @@ Create a container
"Warnings":[]
}
Json Parameters:
Json Parameters:
 
- **config** – the container's configuration
- **config** – the container's configuration
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
### Inspect a container
@ -144,11 +144,11 @@ Create a container
Return low-level information on the container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -199,11 +199,11 @@ Return low-level information on the container `id`
"Volumes": {}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Inspect changes on a container's filesystem
@ -211,11 +211,11 @@ Return low-level information on the container `id`
Inspect changes on container `id`'s filesystem
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/changes HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -235,11 +235,11 @@ Inspect changes on container `id`'s filesystem
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Export a container
@ -247,22 +247,22 @@ Inspect changes on container `id`'s filesystem
Export the contents of container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/export HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/octet-stream
{{ STREAM }}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Start a container
@ -270,19 +270,19 @@ Export the contents of container `id`
Start the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/start HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Stop a container
@ -290,25 +290,25 @@ Start the container `id`
Stop the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/stop?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Restart a container
@ -316,25 +316,25 @@ Stop the container `id`
Restart the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/restart?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Kill a container
@ -342,19 +342,19 @@ Restart the container `id`
Kill the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/kill HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Attach to a container
@ -362,38 +362,38 @@ Kill the container `id`
Attach to the container `id`
**Example request**:
**Example request**:
POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **logs** – 1/True/true or 0/False/false, return logs. Default
- **logs** – 1/True/true or 0/False/false, return logs. Defaul
false
- **stream** – 1/True/true or 0/False/false, return stream.
- **stream** – 1/True/true or 0/False/false, return stream.
Default false
- **stdin** – 1/True/true or 0/False/false, if stream=true, attach
- **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** – 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** – 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
- **404** – no such container
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
### Wait a container
@ -401,22 +401,22 @@ Attach to the container `id`
Block until container `id` stops, then returns the exit code
**Example request**:
**Example request**:
POST /containers/16253994b7c4/wait HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{"StatusCode":0}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Remove a container
@ -424,27 +424,27 @@ Block until container `id` stops, then returns the exit code
Remove the container `id` from the filesystem
**Example request**:
**Example request**:
DELETE /containers/16253994b7c4?v=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **v** – 1/True/true or 0/False/false, Remove the volumes
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default false
Status Codes:
Status Codes:
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
## 2.2 Images
@ -454,11 +454,11 @@ Remove the container `id` from the filesystem
List images `format` could be json or viz (json default)
**Example request**:
**Example request**:
GET /images/json?all=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -478,11 +478,11 @@ List images `format` could be json or viz (json default)
}
]
**Example request**:
**Example request**:
GET /images/viz HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: text/plain
@ -505,30 +505,30 @@ List images `format` could be json or viz (json default)
base [style=invisible]
}
Query Parameters:
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create an image
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
Create an image, either by pull it from the registry or by importing i
**Example request**:
**Example request**:
POST /images/create?fromImage=ubuntu HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -538,20 +538,20 @@ Create an image, either by pull it from the registry or by importing it
{"error":"Invalid..."}
...
Query Parameters:
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
- **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:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Insert a file in an image
@ -559,11 +559,11 @@ Create an image, either by pull it from the registry or by importing it
Insert a file from `url` in the image `name` at `path`
**Example request**:
**Example request**:
POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -573,17 +573,15 @@ Insert a file from `url` in the image `name` at `path`
{"error":"Invalid..."}
...
Query Parameters:
Query Parameters:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Inspect an image
@ -591,11 +589,11 @@ Insert a file from `url` in the image `name` at `path`
Return low-level information on the image `name`
**Example request**:
**Example request**:
GET /images/centos/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -627,11 +625,11 @@ Return low-level information on the image `name`
}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Get the history of an image
@ -639,11 +637,11 @@ Return low-level information on the image `name`
Return the history of the image `name`
**Example request**:
**Example request**:
GET /images/fedora/history HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -661,11 +659,11 @@ Return the history of the image `name`
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Push an image on the registry
@ -687,11 +685,11 @@ Push the image `name` on the registry
{"error":"Invalid..."}
...
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Tag an image into a repository
@ -699,28 +697,28 @@ Push the image `name` on the registry
Tag the image `name` into a repository
**Example request**:
**Example request**:
POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Query Parameters:
Query Parameters:
 
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
Status Codes:
Status Codes:
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflict
- **500** – server error
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflic
- **500** – server error
### Remove an image
@ -728,19 +726,19 @@ Tag the image `name` into a repository
Remove the image `name` from the filesystem
**Example request**:
**Example request**:
DELETE /images/test HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such image
- **500** – server error
- **204** – no error
- **404** – no such image
- **500** – server error
### Search images
@ -748,11 +746,11 @@ Remove the image `name` from the filesystem
Search for an image on [Docker Hub](https://hub.docker.com)
**Example request**:
**Example request**:
GET /images/search?term=sshd HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -784,29 +782,29 @@ Search for an image on [Docker Hub](https://hub.docker.com)
Build an image from Dockerfile via stdin
**Example request**:
**Example request**:
POST /build HTTP/1.1
{{ STREAM }}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **t** – tag to be applied to the resulting image in case of
- **t** – tag to be applied to the resulting image in case of
success
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Get default username and email
@ -814,11 +812,11 @@ Build an image from Dockerfile via stdin
Get the default username and email
**Example request**:
**Example request**:
GET /auth HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -828,18 +826,18 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Check auth configuration and store it
### Check auth configuration and store i
`POST /auth`
Get the default username and email
**Example request**:
**Example request**:
POST /auth HTTP/1.1
Content-Type: application/json
@ -850,15 +848,15 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **204** – no error
- **500** – server error
- **200** – no error
- **204** – no error
- **500** – server error
### Display system-wide information
@ -866,11 +864,11 @@ Get the default username and email
Display system-wide information
**Example request**:
**Example request**:
GET /info HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -885,10 +883,10 @@ Display system-wide information
"SwapLimit":false
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Show the docker version information
@ -896,11 +894,11 @@ Display system-wide information
Show the docker version information
**Example request**:
**Example request**:
GET /version HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -911,10 +909,10 @@ Show the docker version information
"GoVersion":"go1.0.3"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Create a new image from a container's changes
@ -922,7 +920,7 @@ Show the docker version information
Create a new image from a container's changes
**Example request**:
**Example request**:
POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
Content-Type: application/json
@ -932,29 +930,29 @@ Create a new image from a container's changes
"PortSpecs":["22"]
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/vnd.docker.raw-stream
{"Id":"596069db4bf5"}
Query Parameters:
Query Parameters:
 
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **500** – server error
- **201** – no error
- **404** – no such container
- **500** – server error
# 3. Going further
@ -965,7 +963,7 @@ 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
- Try to pull i
- Then retry to create the container
- Start the container

512
docs/sources/reference/api/docker_remote_api_v1.10.md
View File

File diff suppressed because it is too large Load Diff

538
docs/sources/reference/api/docker_remote_api_v1.11.md
View File

File diff suppressed because it is too large Load Diff

570
docs/sources/reference/api/docker_remote_api_v1.12.md
View File

File diff suppressed because it is too large Load Diff

574
docs/sources/reference/api/docker_remote_api_v1.13.md
View File

File diff suppressed because it is too large Load Diff

574
docs/sources/reference/api/docker_remote_api_v1.14.md
View File

File diff suppressed because it is too large Load Diff

584
docs/sources/reference/api/docker_remote_api_v1.15.md
View File

File diff suppressed because it is too large Load Diff

404
docs/sources/reference/api/docker_remote_api_v1.2.md
View File

@ -22,11 +22,11 @@ page_keywords: API, Docker, rcli, REST, documentation
List containers
**Example request**:
**Example request**:
GET /containers/json?all=1&before=8dfafdbc3a40 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -74,24 +74,24 @@ List containers
}
]
Query Parameters:
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
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
- **limit** – Show `limit` last created
containers, include non-running ones.
- **since** – Show only containers created since Id, include
- **since** – Show only containers created since Id, include
non-running ones.
- **before** – Show only containers created before Id, include
- **before** – Show only containers created before Id, include
non-running ones.
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create a container
@ -99,7 +99,7 @@ List containers
Create a container
**Example request**:
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
@ -126,7 +126,7 @@ Create a container
"VolumesFrom":""
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/json
@ -136,18 +136,18 @@ Create a container
"Warnings":[]
}
Json Parameters:
Json Parameters:
 
- **config** – the container's configuration
- **config** – the container's configuration
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
### Inspect a container
@ -156,11 +156,11 @@ Create a container
Return low-level information on the container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -211,11 +211,11 @@ Return low-level information on the container `id`
"Volumes": {}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Inspect changes on a container's filesystem
@ -223,11 +223,11 @@ Return low-level information on the container `id`
Inspect changes on container `id`'s filesystem
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/changes HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -247,11 +247,11 @@ Inspect changes on container `id`'s filesystem
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Export a container
@ -259,22 +259,22 @@ Inspect changes on container `id`'s filesystem
Export the contents of container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/export HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/octet-stream
{{ TAR STREAM }}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Start a container
@ -282,19 +282,19 @@ Export the contents of container `id`
Start the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/start HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Stop a container
@ -302,25 +302,25 @@ Start the container `id`
Stop the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/stop?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Restart a container
@ -328,25 +328,25 @@ Stop the container `id`
Restart the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/restart?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Kill a container
@ -354,19 +354,19 @@ Restart the container `id`
Kill the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/kill HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Attach to a container
@ -374,38 +374,38 @@ Kill the container `id`
Attach to the container `id`
**Example request**:
**Example request**:
POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **logs** – 1/True/true or 0/False/false, return logs. Default
- **logs** – 1/True/true or 0/False/false, return logs. Defaul
false
- **stream** – 1/True/true or 0/False/false, return stream.
- **stream** – 1/True/true or 0/False/false, return stream.
Default false
- **stdin** – 1/True/true or 0/False/false, if stream=true, attach
- **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** – 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** – 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
- **404** – no such container
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
### Wait a container
@ -413,22 +413,22 @@ Attach to the container `id`
Block until container `id` stops, then returns the exit code
**Example request**:
**Example request**:
POST /containers/16253994b7c4/wait HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{"StatusCode":0}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Remove a container
@ -436,27 +436,27 @@ Block until container `id` stops, then returns the exit code
Remove the container `id` from the filesystem
**Example request**:
**Example request**:
DELETE /containers/16253994b7c4?v=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **v** – 1/True/true or 0/False/false, Remove the volumes
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default false
Status Codes:
Status Codes:
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
## 2.2 Images
@ -466,11 +466,11 @@ Remove the container `id` from the filesystem
List images `format` could be json or viz (json default)
**Example request**:
**Example request**:
GET /images/json?all=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -494,11 +494,11 @@ List images `format` could be json or viz (json default)
}
]
**Example request**:
**Example request**:
GET /images/viz HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: text/plain
@ -521,30 +521,30 @@ List images `format` could be json or viz (json default)
base [style=invisible]
}
Query Parameters:
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create an image
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
Create an image, either by pull it from the registry or by importing i
**Example request**:
**Example request**:
POST /images/create?fromImage=ubuntu HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -554,20 +554,20 @@ Create an image, either by pull it from the registry or by importing it
{"error":"Invalid..."}
...
Query Parameters:
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
- **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:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Insert a file in an image
@ -575,11 +575,11 @@ Create an image, either by pull it from the registry or by importing it
Insert a file from `url` in the image `name` at `path`
**Example request**:
**Example request**:
POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -589,17 +589,15 @@ Insert a file from `url` in the image `name` at `path`
{"error":"Invalid..."}
...
Query Parameters:
Query Parameters:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Inspect an image
@ -607,11 +605,11 @@ Insert a file from `url` in the image `name` at `path`
Return low-level information on the image `name`
**Example request**:
**Example request**:
GET /images/centos/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -644,11 +642,11 @@ Return low-level information on the image `name`
"Size": 6824592
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Get the history of an image
@ -656,11 +654,11 @@ Return low-level information on the image `name`
Return the history of the image `name`
**Example request**:
**Example request**:
GET /images/fedora/history HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -679,11 +677,11 @@ Return the history of the image `name`
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Push an image on the registry
@ -706,11 +704,11 @@ Push the image `name` on the registry
{"error":"Invalid..."}
...
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Tag an image into a repository
@ -718,28 +716,28 @@ Push the image `name` on the registry
Tag the image `name` into a repository
**Example request**:
**Example request**:
POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Query Parameters:
Query Parameters:
 
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
Status Codes:
Status Codes:
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflict
- **500** – server error
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflic
- **500** – server error
### Remove an image
@ -747,11 +745,11 @@ Tag the image `name` into a repository
Remove the image `name` from the filesystem
**Example request**:
**Example request**:
DELETE /images/test HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-type: application/json
@ -762,12 +760,12 @@ Remove the image `name` from the filesystem
{"Deleted":"53b4f83ac9"}
]
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such image
- **409** – conflict
- **500** – server error
- **204** – no error
- **404** – no such image
- **409** – conflic
- **500** – server error
### Search images
@ -775,11 +773,11 @@ Remove the image `name` from the filesystem
Search for an image on [Docker Hub](https://hub.docker.com)
**Example request**:
**Example request**:
GET /images/search?term=sshd HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -811,30 +809,30 @@ Search for an image on [Docker Hub](https://hub.docker.com)
Build an image from Dockerfile
**Example request**:
**Example request**:
POST /build HTTP/1.1
{{ TAR STREAM }}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **t** – repository name to be applied to the resulting image in
- **t** – repository name to be applied to the resulting image in
case of success
- **remote** – resource to fetch, as URI
- **remote** – resource to fetch, as URI
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
{{ STREAM }} is the raw text output of the build command. It uses the
HTTP Hijack method in order to stream.
@ -845,7 +843,7 @@ HTTP Hijack method in order to stream.
Get the default username and email
**Example request**:
**Example request**:
POST /auth HTTP/1.1
Content-Type: application/json
@ -856,7 +854,7 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -865,13 +863,13 @@ Get the default username and email
"Status": "Login Succeeded"
}
Status Codes:
Status Codes:
- **200** – no error
- **204** – no error
- **401** – unauthorized
- **403** – forbidden
- **500** – server error
- **200** – no error
- **204** – no error
- **401** – unauthorized
- **403** – forbidden
- **500** – server error
### Display system-wide information
@ -879,11 +877,11 @@ Get the default username and email
Display system-wide information
**Example request**:
**Example request**:
GET /info HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -898,10 +896,10 @@ Display system-wide information
"SwapLimit":false
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Show the docker version information
@ -909,11 +907,11 @@ Display system-wide information
Show the docker version information
**Example request**:
**Example request**:
GET /version HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -924,10 +922,10 @@ Show the docker version information
"GoVersion":"go1.0.3"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Create a new image from a container's changes
@ -935,7 +933,7 @@ Show the docker version information
Create a new image from a container's changes
**Example request**:
**Example request**:
POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
Content-Type: application/json
@ -945,29 +943,29 @@ Create a new image from a container's changes
"PortSpecs":["22"]
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/vnd.docker.raw-stream
{"Id":"596069db4bf5"}
Query Parameters:
Query Parameters:
 
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **500** – server error
- **201** – no error
- **404** – no such container
- **500** – server error
# 3. Going further
@ -978,7 +976,7 @@ 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
- Try to pull i
- Then retry to create the container
- Start the container

436
docs/sources/reference/api/docker_remote_api_v1.3.md
View File

@ -22,11 +22,11 @@ page_keywords: API, Docker, rcli, REST, documentation
List containers
**Example request**:
**Example request**:
GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -74,26 +74,26 @@ List containers
}
]
Query Parameters:
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
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
- **limit** – Show `limit` last created
containers, include non-running ones.
- **since** – Show only containers created since Id, include
- **since** – Show only containers created since Id, include
non-running ones.
- **before** – Show only containers created before Id, include
- **before** – Show only containers created before Id, include
non-running ones.
- **size** – 1/True/true or 0/False/false, Show the containers
- **size** – 1/True/true or 0/False/false, Show the containers
sizes
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create a container
@ -101,7 +101,7 @@ List containers
Create a container
**Example request**:
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
@ -128,7 +128,7 @@ Create a container
"VolumesFrom":""
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/json
@ -138,18 +138,18 @@ Create a container
"Warnings":[]
}
Json Parameters:
Json Parameters:
 
- **config** – the container's configuration
- **config** – the container's configuration
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
- **201** – no error
- **404** – no such container
- **406** – impossible to attach (container not running)
- **500** – server error
### Inspect a container
@ -158,11 +158,11 @@ Create a container
Return low-level information on the container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -213,11 +213,11 @@ Return low-level information on the container `id`
"Volumes": {}
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### List processes running inside a container
@ -225,11 +225,11 @@ Return low-level information on the container `id`
List processes running inside the container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/top HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -249,11 +249,11 @@ List processes running inside the container `id`
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Inspect changes on a container's filesystem
@ -261,11 +261,11 @@ List processes running inside the container `id`
Inspect changes on container `id`'s filesystem
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/changes HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -285,11 +285,11 @@ Inspect changes on container `id`'s filesystem
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Export a container
@ -297,22 +297,22 @@ Inspect changes on container `id`'s filesystem
Export the contents of container `id`
**Example request**:
**Example request**:
GET /containers/4fa6e0f0c678/export HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/octet-stream
{{ TAR STREAM }}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Start a container
@ -320,7 +320,7 @@ Export the contents of container `id`
Start the container `id`
**Example request**:
**Example request**:
POST /containers/(id)/start HTTP/1.1
Content-Type: application/json
@ -329,22 +329,22 @@ Start the container `id`
"Binds":["/tmp:/tmp"]
}
**Example response**:
**Example response**:
HTTP/1.1 204 No Content
HTTP/1.1 204 No Conten
Content-Type: text/plain
Json Parameters:
Json Parameters:
 
- **hostConfig** – the container's host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Stop a container
@ -352,25 +352,25 @@ Start the container `id`
Stop the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/stop?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Restart a container
@ -378,25 +378,25 @@ Stop the container `id`
Restart the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/restart?t=5 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **t** – number of seconds to wait before killing the container
- **t** – number of seconds to wait before killing the container
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Kill a container
@ -404,19 +404,19 @@ Restart the container `id`
Kill the container `id`
**Example request**:
**Example request**:
POST /containers/e90e34656806/kill HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Status Codes:
Status Codes:
- **204** – no error
- **404** – no such container
- **500** – server error
- **204** – no error
- **404** – no such container
- **500** – server error
### Attach to a container
@ -424,38 +424,38 @@ Kill the container `id`
Attach to the container `id`
**Example request**:
**Example request**:
POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
{{ STREAM }}
Query Parameters:
Query Parameters:
 
- **logs** – 1/True/true or 0/False/false, return logs. Default
- **logs** – 1/True/true or 0/False/false, return logs. Defaul
false
- **stream** – 1/True/true or 0/False/false, return stream.
- **stream** – 1/True/true or 0/False/false, return stream.
Default false
- **stdin** – 1/True/true or 0/False/false, if stream=true, attach
- **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** – 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** – 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
- **404** – no such container
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
### Wait a container
@ -463,22 +463,22 @@ Attach to the container `id`
Block until container `id` stops, then returns the exit code
**Example request**:
**Example request**:
POST /containers/16253994b7c4/wait HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{"StatusCode":0}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such container
- **500** – server error
- **200** – no error
- **404** – no such container
- **500** – server error
### Remove a container
@ -486,27 +486,27 @@ Block until container `id` stops, then returns the exit code
Remove the container `id` from the filesystem
**Example request**:
**Example request**:
DELETE /containers/16253994b7c4?v=1 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 204 OK
Query Parameters:
Query Parameters:
 
- **v** – 1/True/true or 0/False/false, Remove the volumes
- **v** – 1/True/true or 0/False/false, Remove the volumes
associated to the container. Default false
Status Codes:
Status Codes:
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
- **204** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
## 2.2 Images
@ -516,11 +516,11 @@ Remove the container `id` from the filesystem
List images `format` could be json or viz (json default)
**Example request**:
**Example request**:
GET /images/json?all=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -544,11 +544,11 @@ List images `format` could be json or viz (json default)
}
]
**Example request**:
**Example request**:
GET /images/viz HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: text/plain
@ -571,30 +571,30 @@ List images `format` could be json or viz (json default)
base [style=invisible]
}
Query Parameters:
Query Parameters:
 
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by default
- **all** – 1/True/true or 0/False/false, Show all containers.
Only running containers are shown by defaul
Status Codes:
Status Codes:
- **200** – no error
- **400** – bad parameter
- **500** – server error
- **200** – no error
- **400** – bad parameter
- **500** – server error
### Create an image
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
Create an image, either by pull it from the registry or by importing i
**Example request**:
**Example request**:
POST /images/create?fromImage=ubuntu HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -604,20 +604,20 @@ Create an image, either by pull it from the registry or by importing it
{"error":"Invalid..."}
...
Query Parameters:
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
- **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:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Insert a file in an image
@ -625,11 +625,11 @@ Create an image, either by pull it from the registry or by importing it
Insert a file from `url` in the image `name` at `path`
**Example request**:
**Example request**:
POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -639,17 +639,15 @@ Insert a file from `url` in the image `name` at `path`
{"error":"Invalid..."}
...
Query Parameters:
Query Parameters:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **url** – The url from where the file is taken
- **path** – The path where the file is stored
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Inspect an image
@ -657,11 +655,11 @@ Insert a file from `url` in the image `name` at `path`
Return low-level information on the image `name`
**Example request**:
**Example request**:
GET /images/centos/json HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -694,11 +692,11 @@ Return low-level information on the image `name`
"Size": 6824592
}
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Get the history of an image
@ -706,11 +704,11 @@ Return low-level information on the image `name`
Return the history of the image `name`
**Example request**:
**Example request**:
GET /images/fedora/history HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -728,11 +726,11 @@ Return the history of the image `name`
}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Push an image on the registry
@ -755,11 +753,11 @@ Push the image `name` on the registry
{"error":"Invalid..."}
...
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **500** – server error
- **200** – no error
- **404** – no such image
- **500** – server error
### Tag an image into a repository
@ -767,28 +765,28 @@ Push the image `name` on the registry
Tag the image `name` into a repository
**Example request**:
**Example request**:
POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Query Parameters:
Query Parameters:
 
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
Status Codes:
Status Codes:
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflict
- **500** – server error
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflic
- **500** – server error
### Remove an image
@ -796,11 +794,11 @@ Tag the image `name` into a repository
Remove the image `name` from the filesystem
**Example request**:
**Example request**:
DELETE /images/test HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-type: application/json
@ -811,12 +809,12 @@ Remove the image `name` from the filesystem
{"Deleted":"53b4f83ac9"}
]
Status Codes:
Status Codes:
- **200** – no error
- **404** – no such image
- **409** – conflict
- **500** – server error
- **200** – no error
- **404** – no such image
- **409** – conflic
- **500** – server error
### Search images
@ -824,11 +822,11 @@ Remove the image `name` from the filesystem
Search for an image on [Docker Hub](https://hub.docker.com)
**Example request**:
**Example request**:
GET /images/search?term=sshd HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -860,13 +858,13 @@ Search for an image on [Docker Hub](https://hub.docker.com)
Build an image from Dockerfile via stdin
**Example request**:
**Example request**:
POST /build HTTP/1.1
{{ TAR STREAM }}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
@ -874,24 +872,24 @@ Build an image from Dockerfile via stdin
The stream must be a tar archive compressed with one of the
following algorithms: identity (no compression), gzip, bzip2, xz.
The archive must include a file called Dockerfile at its root. It
The archive must include a file called Dockerfile at its root. I
may include any number of other files, which will be accessible in
the build context (See the ADD build command).
The Content-type header should be set to "application/tar".
Query Parameters:
Query Parameters:
 
- **t** – repository name (and optionally a tag) to be applied to
- **t** – repository name (and optionally a tag) to be applied to
the resulting image in case of success
- **q** – suppress verbose build output
- **q** – suppress verbose build outpu
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Check auth configuration
@ -899,7 +897,7 @@ Build an image from Dockerfile via stdin
Get the default username and email
**Example request**:
**Example request**:
POST /auth HTTP/1.1
Content-Type: application/json
@ -910,15 +908,15 @@ Get the default username and email
"email":"hannibal@a-team.com"
}
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Status Codes:
Status Codes:
- **200** – no error
- **204** – no error
- **500** – server error
- **200** – no error
- **204** – no error
- **500** – server error
### Display system-wide information
@ -926,11 +924,11 @@ Get the default username and email
Display system-wide information
**Example request**:
**Example request**:
GET /info HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -948,10 +946,10 @@ Display system-wide information
"KernelVersion":"3.8.0-19-generic"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Show the docker version information
@ -959,11 +957,11 @@ Display system-wide information
Show the docker version information
**Example request**:
**Example request**:
GET /version HTTP/1.1
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -974,10 +972,10 @@ Show the docker version information
"GoVersion":"go1.0.3"
}
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
### Create a new image from a container's changes
@ -985,7 +983,7 @@ Show the docker version information
Create a new image from a container's changes
**Example request**:
**Example request**:
POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
Content-Type: application/json
@ -995,29 +993,29 @@ Create a new image from a container's changes
"PortSpecs":["22"]
}
**Example response**:
**Example response**:
HTTP/1.1 201 OK
Content-Type: application/vnd.docker.raw-stream
{"Id":"596069db4bf5"}
Query Parameters:
Query Parameters:
 
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
- **container** – source container
- **repo** – repository
- **tag** – tag
- **m** – commit message
- **author** – author (e.g., "John Hannibal Smith
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
Status Codes:
- **201** – no error
- **404** – no such container
- **500** – server error
- **201** – no error
- **404** – no such container
- **500** – server error
### Monitor Docker's events
@ -1026,11 +1024,11 @@ Create a new image from a container's changes
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
**Example request**:
GET /events?since=1374067924
**Example response**:
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
@ -1040,16 +1038,16 @@ polling (using since)
{"status":"stop","id":"dfdf82bd3881","time":1374067966}
{"status":"destroy","id":"dfdf82bd3881","time":1374067970}
Query Parameters:
Query Parameters:
 
- **since** – timestamp used for polling
- **since** – timestamp used for polling
Status Codes:
Status Codes:
- **200** – no error
- **500** – server error
- **200** – no error
- **500** – server error
# 3. Going further
@ -1060,7 +1058,7 @@ 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
- Try to pull i
- Then retry to create the container
- Start the container

458
docs/sources/reference/api/docker_remote_api_v1.4.md
View File

File diff suppressed because it is too large Load Diff

468
docs/sources/reference/api/docker_remote_api_v1.5.md
View File

File diff suppressed because it is too large Load Diff

480
docs/sources/reference/api/docker_remote_api_v1.6.md
View File

File diff suppressed because it is too large Load Diff

478
docs/sources/reference/api/docker_remote_api_v1.7.md
View File

File diff suppressed because it is too large Load Diff

514
docs/sources/reference/api/docker_remote_api_v1.8.md
View File

File diff suppressed because it is too large Load Diff

530
docs/sources/reference/api/docker_remote_api_v1.9.md
View File

File diff suppressed because it is too large Load Diff

228
docs/sources/reference/api/hub_registry_spec.md
View File

@ -133,41 +133,49 @@ and for an active account.
1. (Docker -> Docker Hub) GET /v1/repositories/foo/bar/images:
**Headers**:
**Headers**:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-Docker-Token: true
**Action**:
**Action**:
(looking up the foo/bar in db and gets images and checksums
for that repo (all if no tag is specified, if tag, only
checksums for those tags) see part 4.4.1)
2. (Docker Hub -> Docker) HTTP 200 OK
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
X-Docker-Endpoints: registry.docker.io [,registry2.docker.io]
**Body**:
**Body**:
Jsonified checksums (see part 4.4.1)
3. (Docker -> Registry) GET /v1/repositories/foo/bar/tags/latest
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry -> Docker Hub) GET /v1/repositories/foo/bar/images
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=read
**Body**:
**Body**:
<ids and checksums in payload>
**Action**:
**Action**:
(Lookup token see if they have access to pull.)
If good:
@ -178,7 +186,8 @@ and for an active account.
5. (Docker -> Registry) GET /v1/images/928374982374/ancestry
**Action**:
**Action**:
(for each image id returned in the registry, fetch /json + /layer)
> **Note**:
@ -220,92 +229,108 @@ the end).
1. (Docker -> Docker Hub) PUT /v1/repositories/foo/bar/
**Headers**:
**Headers**:
Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Action**:
- in Docker Hub, we allocated a new repository, and set to
initialized
**Action**:
**Body**:
(The body contains the list of images that are going to be
pushed, with empty checksums. The checksums will be set at
the end of the push):
- in Docker Hub, we allocated a new repository, and set to
initialized
**Body**:
(The body contains the list of images that are going to be
pushed, with empty checksums. The checksums will be set at
the end of the push):
[{“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”}]
2. (Docker Hub -> Docker) 200 Created
**Headers**:
- WWW-Authenticate: Token
**Headers**:
WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=write
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io]
X-Docker-Endpoints: registry.docker.io [, registry2.docker.io]
3. (Docker -> Registry) PUT /v1/images/98765432_parent/json
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry->Docker Hub) GET /v1/repositories/foo/bar/images
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
**Action**:
- Docker Hub:
will invalidate the token.
- Registry:
grants a session (if token is approved) and fetches
the images id
**Action**:
- Docker Hub:
will invalidate the token.
- Registry:
grants a session (if token is approved) and fetches
the images id
5. (Docker -> Registry) PUT /v1/images/98765432_parent/json
**Headers**::
- Authorization: Token
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
- Cookie: (Cookie provided by the Registry)
Cookie: (Cookie provided by the Registry)
6. (Docker -> Registry) PUT /v1/images/98765432/json
**Headers**:
- Cookie: (Cookie provided by the Registry)
**Headers**:
Cookie: (Cookie provided by the Registry)
7. (Docker -> Registry) PUT /v1/images/98765432_parent/layer
**Headers**:
- Cookie: (Cookie provided by the Registry)
**Headers**:
Cookie: (Cookie provided by the Registry)
8. (Docker -> Registry) PUT /v1/images/98765432/layer
**Headers**:
**Headers**:
X-Docker-Checksum: sha256:436745873465fdjkhdfjkgh
9. (Docker -> Registry) PUT /v1/repositories/foo/bar/tags/latest
**Headers**:
- Cookie: (Cookie provided by the Registry)
**Headers**:
Cookie: (Cookie provided by the Registry)
**Body**:
**Body**:
“98765432”
10. (Docker -> Docker Hub) PUT /v1/repositories/foo/bar/images
**Headers**:
**Headers**:
Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
registry1.docker.io (no validation on this right now)
**Body**:
**Body**:
(The image, id`s, tags and checksums)
[{“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}]
**Return**: HTTP 204
**Return**:
HTTP 204
> **Note:** If push fails and they need to start again, what happens in the Docker Hub,
> there will already be a record for the namespace/name, but it will be
@ -344,43 +369,49 @@ nice clean way to do that. Here is the workflow.
1. (Docker -> Docker Hub) DELETE /v1/repositories/foo/bar/
**Headers**:
**Headers**:
Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Action**:
- in Docker Hub, we make sure it is a valid repository, and set
to deleted (logically)
**Action**:
- in Docker Hub, we make sure it is a valid repository, and set
to deleted (logically)
**Body**:
**Body**:
Empty
2. (Docker Hub -> Docker) 202 Accepted
**Headers**:
- WWW-Authenticate: Token
**Headers**:
WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=delete
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io]
X-Docker-Endpoints: registry.docker.io [, registry2.docker.io]
# list of endpoints where this repo lives.
3. (Docker -> Registry) DELETE /v1/repositories/foo/bar/
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
4. (Registry->Docker Hub) PUT /v1/repositories/foo/bar/auth
**Headers**:
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
**Action**:
- Docker Hub:
will invalidate the token.
- Registry:
deletes the repository (if token is approved)
**Action**:
- Docker Hub:
will invalidate the token.
- Registry:
deletes the repository (if token is approved)
5. (Registry -> Docker) 200 OK
@ -389,14 +420,18 @@ nice clean way to do that. Here is the workflow.
6. (Docker -> Docker Hub) DELETE /v1/repositories/foo/bar/
**Headers**:
**Headers**:
Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
registry-1.docker.io (no validation on this right now)
**Body**:
**Body**:
Empty
**Return**: HTTP 200
**Return**:
HTTP 200
## How to use the Registry in standalone mode
@ -478,16 +513,20 @@ file is empty.
POST /v1/users:
**Body**:
**Body**:
{"email": "[sam@docker.com](mailto:sam%40docker.com)",
"password": "toto42", "username": "foobar"`}
**Validation**:
- **username**: min 4 character, max 30 characters, must match the
regular expression [a-z0-9_].
- **password**: min 5 characters
**Validation**:
**Valid**: return HTTP 200
- **username**: min 4 character, max 30 characters, must match the
regular expression [a-z0-9_].
- **password**: min 5 characters
**Valid**:
return HTTP 200
Errors: HTTP 400 (we should create error codes for possible errors) -
invalid json - missing field - wrong format (username, password, email,
@ -501,7 +540,8 @@ etc) - forbidden name - name already exists
PUT /v1/users/<username>
**Body**:
**Body**:
{"password": "toto"}
> **Note**:
@ -515,10 +555,10 @@ validate credentials. HTTP Basic Auth for now, maybe change in future.
GET /v1/users
**Return**:
- Valid: HTTP 200
- Invalid login: HTTP 401
- Account inactive: HTTP 403 Account is not Active
**Return**:
- Valid: HTTP 200
- Invalid login: HTTP 401
- Account inactive: HTTP 403 Account is not Active
### Tags (Registry)
@ -543,14 +583,15 @@ GET /v1/repositories/<namespace>/<repository_name>/tags
“0.1.1”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087” }
**4.3.2 Read the content of a tag (resolve the image id):**
**4.3.2 Read the content of a tag (resolve the image id):**
GET /v1/repositories/<namespace>/<repo_name>/tags/<tag>
**Return**:
**Return**:
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
**4.3.3 Delete a tag (registry):**
**4.3.3 Delete a tag (registry):**
DELETE /v1/repositories/<namespace>/<repo_name>/tags/<tag>
@ -577,14 +618,17 @@ You always add images, you never remove them.
PUT /v1/repositories/<namespace>/<repo_name>/images
**Body**:
**Body**:
[ {“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“sha256:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}
]
**Return**: 204
**Return**:
204
### Repositories
@ -640,28 +684,32 @@ You have 3 options:
1. Provide user credentials and ask for a token
**Header**:
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
- X-Docker-Token: true
**Header**:
In this case, along with the 200 response, you'll get a new token
(if user auth is ok): If authorization isn't correct you get a 401
response. If account isn't active you will get a 403 response.
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-Docker-Token: true
**Response**:
- 200 OK
- X-Docker-Token: Token
signature=123abc,repository=”foo/bar”,access=read
In this case, along with the 200 response, you'll get a new token
(if user auth is ok): If authorization isn't correct you get a 401
response. If account isn't active you will get a 403 response.
**Response**:
200 OK
X-Docker-Token: Token
signature=123abc,repository=”foo/bar”,access=read
2. Provide user credentials only
**Header**:
**Header**:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
3. Provide Token
**Header**:
**Header**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=read

207
docs/sources/reference/api/registry_api.md
View File

@ -73,13 +73,13 @@ The default namespace for a private repository is `library`.
## Images
### Layer
### Get image layer
`GET /v1/images/(image_id)/layer`
Get image layer for a given `image_id`
**Example Request**:
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1
Host: registry-1.docker.io
@ -87,11 +87,11 @@ Get image layer for a given `image_id`
Content-Type: application/json
Authorization: Token signature=123abc,repository="foo/bar",access=read
Parameters:
Parameters:
- **image_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -100,17 +100,19 @@ Get image layer for a given `image_id`
{layer binary data stream}
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
### Put image layer
`PUT /v1/images/(image_id)/layer`
Put image layer for a given `image_id`
**Example Request**:
**Example Request**:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1
Host: registry-1.docker.io
@ -119,11 +121,11 @@ Put image layer for a given `image_id`
{layer binary data stream}
Parameters:
Parameters:
- **image_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -132,19 +134,21 @@ Put image layer for a given `image_id`
""
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
## Image
### Put image layer
`PUT /v1/images/(image_id)/json`
Put image for a given `image_id`
**Example Request**:
**Example Request**:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1
Host: registry-1.docker.io
@ -183,11 +187,11 @@ Put image for a given `image_id`
docker_version: "0.1.7"
}
Parameters:
Parameters:
- **image_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -196,16 +200,18 @@ Put image for a given `image_id`
""
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **200** – OK
- **401** – Requires authorization
### Get image layer
`GET /v1/images/(image_id)/json`
Get image for a given `image_id`
**Example Request**:
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1
Host: registry-1.docker.io
@ -213,11 +219,11 @@ Get image for a given `image_id`
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
Parameters:
- **image_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -257,19 +263,21 @@ Get image for a given `image_id`
docker_version: "0.1.7"
}
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
## Ancestry
### Get image ancestry
`GET /v1/images/(image_id)/ancestry`
Get ancestry for an image given an `image_id`
**Example Request**:
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/ancestry HTTP/1.1
Host: registry-1.docker.io
@ -277,11 +285,11 @@ Get ancestry for an image given an `image_id`
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
Parameters:
- **image_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -293,19 +301,21 @@ Get ancestry for an image given an `image_id`
"bfa4c5326bc764280b0863b46a4b20d940bc1897ef9c1dfec060604bdc383280",
"6ab5893c6927c15a15665191f2c6cf751f5056d8b95ceee32e43c5e8a3648544"]
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
## Tags
### List repository tags
`GET /v1/repositories/(namespace)/(repository)/tags`
Get all of the tags for the given repo.
**Example Request**:
**Example Request**:
GET /v1/repositories/reynholm/help-system-server/tags HTTP/1.1
Host: registry-1.docker.io
@ -314,12 +324,12 @@ Get all of the tags for the given repo.
X-Docker-Registry-Version: 0.6.0
Cookie: (Cookie provided by the Registry)
Parameters:
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **namespace** – namespace for the repo
- **repository** – name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -331,17 +341,19 @@ Get all of the tags for the given repo.
"0.1.1": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"
}
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
### Get image id for a particular tag
`GET /v1/repositories/(namespace)/(repository)/tags/(tag*)`
Get a tag for the given repo.
**Example Request**:
**Example Request**:
GET /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1
Host: registry-1.docker.io
@ -350,13 +362,13 @@ Get a tag for the given repo.
X-Docker-Registry-Version: 0.6.0
Cookie: (Cookie provided by the Registry)
Parameters:
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to get
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to get
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -365,17 +377,19 @@ Get a tag for the given repo.
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
### Delete a repository tag
`DELETE /v1/repositories/(namespace)/(repository)/tags/(tag*)`
Delete the tag for the repo
**Example Request**:
**Example Request**:
DELETE /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1
Host: registry-1.docker.io
@ -383,13 +397,13 @@ Delete the tag for the repo
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to delete
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to delete
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -398,17 +412,19 @@ Delete the tag for the repo
""
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
### Set a tag for a specified image id
`PUT /v1/repositories/(namespace)/(repository)/tags/(tag*)`
Put a tag for the given repo.
**Example Request**:
**Example Request**:
PUT /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1
Host: registry-1.docker.io
@ -418,13 +434,13 @@ Put a tag for the given repo.
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Parameters:
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to add
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to add
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -433,20 +449,22 @@ Put a tag for the given repo.
""
Status Codes:
Status Codes:
- **200** – OK
- **400** – Invalid data
- **401** – Requires authorization
- **404** – Image not found
- **200** – OK
- **400** – Invalid data
- **401** – Requires authorization
- **404** – Image not found
## Repositories
### Delete a repository
`DELETE /v1/repositories/(namespace)/(repository)/`
Delete a repository
**Example Request**:
**Example Request**:
DELETE /v1/repositories/reynholm/help-system-server/ HTTP/1.1
Host: registry-1.docker.io
@ -456,12 +474,12 @@ Delete a repository
""
Parameters:
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **namespace** – namespace for the repo
- **repository** – name for the repo
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -470,20 +488,22 @@ Delete a repository
""
Status Codes:
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
## Status
### Status check for registry
`GET /v1/_ping`
Check status of the registry. This endpoint is also used to
determine if the registry supports SSL.
**Example Request**:
**Example Request**:
GET /v1/_ping HTTP/1.1
Host: registry-1.docker.io
@ -492,7 +512,7 @@ determine if the registry supports SSL.
""
**Example Response**:
**Example Response**:
HTTP/1.1 200
Vary: Accept
@ -501,13 +521,12 @@ determine if the registry supports SSL.
""
Status Codes:
Status Codes:
- **200** – OK
- **200** – OK
## Authorization
This is where we describe the authorization process, including the
tokens and cookies.
TODO: add more info.