page_title: Registry API page_description: API Documentation for Docker Registry page_keywords: API, Docker, index, registry, REST, documentation
We expect that there will be multiple registries out there. To help to grasp the context, here are some examples of registries:
docker pull
those images locally.docker pull basho/riak1.3
and automatically push from the vendor registry (instead of a sponsor registry); i.e., get all the convenience of a sponsor registry, while retaining control on the asset distribution.Note: Mirror registries and private registries which do not use the Index don't even need to run the registry code. They can be implemented by any kind of transport implementing HTTP GET and PUT. Read-only registries can be powered by a simple static HTTPS server.
Note: The latter implies that while HTTP is the protocol of choice for a registry, multiple schemes are possible (and in some cases, trivial):
- HTTP with GET (and PUT for read-write registries);
- local mount point;
- remote Docker addressed through SSH.
The latter would only require two new commands in Docker, e.g., registryget
and registryput
, wrapping access to the local filesystem (and optionally doing consistency checks). Authentication and authorization are then delegated to SSH (e.g., with public keys).
Note: Private registry servers that expose an HTTP endpoint need to be secured with TLS (preferably TLSv1.2, but at least TLSv1.0). Make sure to put the CA certificate at /etc/docker/certs.d/my.registry.com:5000/ca.crt on the Docker host, so that the daemon can securely access the private registry. Support for SSLv3 and lower is not available due to security issues.
The default namespace for a private repository is library
.
GET /v1/images/(image_id)/layer
Get image layer for a given image_id
Example Request:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Authorization: Token signature=123abc,repository="foo/bar",access=read
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry) {layer binary data stream}
Status Codes:
PUT /v1/images/(image_id)/layer
Put image layer for a given image_id
Example Request:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1 Host: registry-1.docker.io Transfer-Encoding: chunked Authorization: Token signature=123abc,repository="foo/bar",access=write {layer binary data stream}
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
PUT /v1/images/(image_id)/json
Put image for a given image_id
Example Request:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) { id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c", parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f", created: "2013-04-30T17:46:10.843673+03:00", container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7", container_config: { Hostname: "host-test", User: "", Memory: 0, MemorySwap: 0, AttachStdin: false, AttachStdout: false, AttachStderr: false, PortSpecs: null, Tty: false, OpenStdin: false, StdinOnce: false, Env: null, Cmd: [ "/bin/bash", "-c", "apt-get -q -yy -f install libevent-dev" ], Dns: null, Image: "imagename/blah", Volumes: { }, VolumesFrom: "" }, docker_version: "0.1.7" }
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
GET /v1/images/(image_id)/json
Get image for a given image_id
Example Request:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry)
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 X-Docker-Size: 456789 X-Docker-Checksum: b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087 { id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c", parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f", created: "2013-04-30T17:46:10.843673+03:00", container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7", container_config: { Hostname: "host-test", User: "", Memory: 0, MemorySwap: 0, AttachStdin: false, AttachStdout: false, AttachStderr: false, PortSpecs: null, Tty: false, OpenStdin: false, StdinOnce: false, Env: null, Cmd: [ "/bin/bash", "-c", "apt-get -q -yy -f install libevent-dev" ], Dns: null, Image: "imagename/blah", Volumes: { }, VolumesFrom: "" }, docker_version: "0.1.7" }
Status Codes:
GET /v1/images/(image_id)/ancestry
Get ancestry for an image given an image_id
Example Request:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/ancestry HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry)
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ["088b4502f51920fbd9b7c503e87c7a2c05aa3adc3d35e79c031fa126b403200f", "aeee63968d87c7da4a5cf5d2be6bee4e21bc226fd62273d180a49c96c62e4543", "bfa4c5326bc764280b0863b46a4b20d940bc1897ef9c1dfec060604bdc383280", "6ab5893c6927c15a15665191f2c6cf751f5056d8b95ceee32e43c5e8a3648544"]
Status Codes:
GET /v1/repositories/(namespace)/(repository)/tags
Get all of the tags for the given repo.
Example Request:
GET /v1/repositories/reynholm/help-system-server/tags HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry)
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 { "latest": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f", "0.1.1": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087" }
Status Codes:
GET /v1/repositories/(namespace)/(repository)/tags/(tag*)
Get a tag for the given repo.
Example Request:
GET /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry)
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Status Codes:
DELETE /v1/repositories/(namespace)/(repository)/tags/(tag*)
Delete the tag for the repo
Example Request:
DELETE /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry)
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
PUT /v1/repositories/(namespace)/(repository)/tags/(tag*)
Put a tag for the given repo.
Example Request:
PUT /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
DELETE /v1/repositories/(namespace)/(repository)/
Delete a repository
Example Request:
DELETE /v1/repositories/reynholm/help-system-server/ HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) ""
Parameters:
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
If you need to search the index, this is the endpoint you would use.
GET /v1/search
Search the Index given a search term. It accepts
[GET](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3) only.
Example request:
GET /v1/search?q=search_term&page=1&n=25 HTTP/1.1 Host: index.docker.io Accept: application/json
Query Parameters:
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json {"num_pages": 1, "num_results": 3, "results" : [ {"name": "ubuntu", "description": "An ubuntu image..."}, {"name": "centos", "description": "A centos image..."}, {"name": "fedora", "description": "A fedora image..."} ], "page_size": 25, "query":"search_term", "page": 1 }
Response Items:
Status Codes:
GET /v1/_ping
Check status of the registry. This endpoint is also used to determine if the registry supports SSL.
Example Request:
GET /v1/_ping HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json ""
Example Response:
HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ""
Status Codes:
This is where we describe the authorization process, including the tokens and cookies.