# Docker Registry HTTP API V2 ## Introduction The _Docker Registry HTTP API_ is the protocol to facilitate distribution of images to the docker engine. It interacts with instances of the docker registry, which is a service to manage information about docker images and enable their distribution. The specification covers the operation of version 2 of this API, known as _Docker Registry HTTP API V2_. While the V1 registry protocol is usable, there are several problems with the architecture that have led to this new version. The main driver of this specification these changes to the docker the image format, covered in docker/docker#8093. The new, self-contained image manifest simplifies image definition and improves security. This specification will build on that work, leveraging new properties of the manifest format to improve performance, reduce bandwidth usage and decrease the likelihood of backend corruption. For relevant details and history leading up to this specification, please see the following issues: - docker/docker#8093 - docker/docker#9015 - docker/docker-registry#612 ### Scope This specification covers the URL layout and protocols of the interaction between docker registry and docker core. This will affect the docker core registry API and the rewrite of docker-registry. Docker registry implementations may implement other API endpoints, but they are not covered by this specification. This includes the following features: - Namespace-oriented URI Layout - PUSH/PULL registry server for V2 image manifest format - Resumable layer PUSH support - V2 Client library implementation While authentication and authorization support will influence this specification, details of the protocol will be left to a future specification. Relevant header definitions and error codes are present to provide an indication of what a client may encounter. #### Future There are features that have been discussed during the process of cutting this specification. The following is an incomplete list: - Immutable image references - Multiple architecture support - Migration from v2compatibility representation These may represent features that are either out of the scope of this specification, the purview of another specification or have been deferred to a future version. ### Use Cases For the most part, the use cases of the former registry API apply to the new version. Differentiating use cases are covered below. #### Image Verification A docker engine instance would like to run verified image named "library/ubuntu", with the tag "latest". The engine contacts the registry, requesting the manifest for "library/ubuntu:latest". An untrusted registry returns a manifest. Before proceeding to download the individual layers, the engine verifies the manifest's signature, ensuring that the content was produced from a trusted source and no tampering has occured. After each layer is downloaded, the engine verifies the digest of the layer, ensuring that the content matches that specified by the manifest. #### Resumable Push Company X's build servers lose connectivity to docker registry before completing an image layer transfer. After connectivity returns, the build server attempts to re-upload the image. The registry notifies the build server that the upload has already been partially attempted. The build server responds by only sending the remaining data to complete the image file. #### Resumable Pull Company X is having more connectivity problems but this time in their deployment datacenter. When downloading an image, the connection is interrupted before completion. The client keeps the partial data and uses http `Range` requests to avoid downloading repeated data. #### Layer Upload De-duplication Company Y's build system creates two identical docker layers from build processes A and B. Build process A completes uploading the layer before B. When process B attempts to upload the layer, the registry indicates that its not necessary because the layer is already known. If process A and B upload the same layer at the same time, both operations will proceed and the first to complete will be stored in the registry (Note: we may modify this to prevent dogpile with some locking mechanism). ### Changes The V2 specification has been written to work as a living document, specifying only what is certain and leaving what is not specified open or to future changes. Only non-conflicting additions should be made to the API and accepted changes should avoid preventing future changes from happening. This section should be updated when changes are made to the specification, indicating what is different. Optionally, we may start marking parts of the specification to correspond with the versions enumerated here.
2.0
This is the baseline specification.
## Overview This section covers client flows and details of the API endpoints. The URI layout of the new API is structured to support a rich authentication and authorization model by leveraging namespaces. All endpoints will be prefixed by the API version and the repository name: /v2// For example, an API endpoint that will work with the `library/ubuntu` repository, the URI prefix will be: /v2/library/ubuntu/ This scheme provides rich access control over various operations and methods using the URI prefix and http methods that can be controlled in variety of ways. Classically, repository names have always been two path components where each path component is less than 30 characters. The V2 registry API does not enforce this. The rules for a repository name are as follows: 1. A repository name is broken up into _path components_. A component of a repository name must be at least two lowercase, alpha-numeric characters, optionally separated by periods, dashes or underscores. More strictly, it must match the regular expression `[a-z0-9]+(?:[._-][a-z0-9]+)*` and the matched result must be 2 or more characters in length. 2. The name of a repository must have at least two path components, separated by a forward slash. 3. The total length of a repository name, including slashes, must be less the 256 characters. These name requirements _only_ apply to the registry API and should accept a superset of what is supported by other docker ecosystem components. All endpoints should support aggressive http caching, compression and range headers, where appropriate. The new API attempts to leverage HTTP semantics where possible but may break from standards to implement targeted features. For detail on individual endpoints, please see the [_Detail_](#detail) section. ### Errors Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body. One or more errors will be returned in the following format: { "errors:" [{ "code": , "message": , "detail": }, ... ] } The `code` field will be a unique identifier, all caps with underscores by convention. The `message` field will be a human readable string. The optional `detail` field may contain arbitrary json data providing information the client can use to resolve the issue. While the client can take action on certain error codes, the registry may add new error codes over time. All client implementations should treat unknown error codes as `UNKNOWN`, allowing future error codes to be added without breaking API compatibility. For the purposes of the specification error codes will only be added and never removed. For a complete account of all error codes, please see the _Detail_ section. ### API Version Check A minimal endpoint, mounted at `/v2/` will provide version support information based on its response statuses. The request format is as follows: GET /v2/ If a `200 OK` response is returned, the registry implements the V2(.1) registry API and the client may proceed safely with other V2 operations. Optionally, the response may contain information about the supported paths in the response body. The client should be prepared to ignore this data. If a `401 Unauthorized` response is returned, the client should take action based on the contents of the "WWW-Authenticate" header and try the endpoint again. Depending on access control setup, the client may still have to authenticate against different resources, even if this check succeeds. If `404 Not Found` response status, or other unexpected status, is returned, the client should proceed with the assumption that the registry does not implement V2 of the API. ### Pulling An Image An "image" is a combination of a JSON manifest and individual layer files. The process of pulling an image centers around retrieving these two components. The first step in pulling an image is to retrieve the manifest. For reference, the relevant manifest fields for the registry are the following: field | description | ----------|------------------------------------------------| name | The name of the image. | tag | The tag for this version of the image. | fsLayers | A list of layer descriptors (including tarsum) | signature | A JWS used to verify the manifest content | For more information about the manifest format, please see [docker/docker#8093](https://github.com/docker/docker/issues/8093). When the manifest is in hand, the client must verify the signature to ensure the names and layers are valid. Once confirmed, the client will then use the tarsums to download the individual layers. Layers are stored in as blobs in the V2 registry API, keyed by their tarsum digest. #### Pulling an Image Manifest The image manifest can be fetched with the following url: ``` GET /v2//manifests/ ``` The "name" and "tag" parameter identify the image and are required. A `404 Not Found` response will be returned if the image is unknown to the registry. If the image exists and the response is successful, the image manifest will be returned, with the following format (see docker/docker#8093 for details): { "name": , "tag": , "fsLayers": [ { "blobSum": }, ... ] ], "history": , "signature": } The client should verify the returned manifest signature for authenticity before fetching layers. #### Pulling a Layer Layers are stored in the blob portion of the registry, keyed by tarsum digest. Pulling a layer is carried out by a standard http request. The URL is as follows: GET /v2//blobs/ Access to a layer will be gated by the `name` of the repository but is identified uniquely in the registry by `tarsum`. The `tarsum` parameter is an opaque field, to be interpreted by the tarsum library. This endpoint may issue a 307 (302 for /blobs/uploads/ ``` The parameters of this request are the image namespace under which the layer will be linked. Responses to this request are covered below. ##### Existing Layers The existence of a layer can be checked via a `HEAD` request to the blob store API. The request should be formatted as follows: ``` HEAD /v2//blobs/ ``` If the layer with the tarsum specified in `digest` is available, a 200 OK response will be received, with no actual body content (this is according to http specification). The response will look as follows: ``` 200 OK Content-Length: ``` When this response is received, the client can assume that the layer is already available in the registry under the given name and should take no further action to upload the layer. Note that the binary digests may differ for the existing registry layer, but the tarsums will be guaranteed to match. ##### Uploading the Layer If the POST request is successful, a `202 Accepted` response will be returned with the upload URL in the `Location` header: ``` 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- Content-Length: 0 ``` The rest of the upload process can be carried out with the returned url, called the "Upload URL" from the `Location` header. All responses to the upload url, whether sending data or getting status, will be in this format. Though the URI format (`/v2//blobs/uploads/`) for the `Location` header is specified, clients should treat it as an opaque url and should never try to assemble the it. While the `uuid` parameter may be an actual UUID, this proposal imposes no constraints on the format and clients should never impose any. ##### Upload Progress The progress and chunk coordination of the upload process will be coordinated through the `Range` header. While this is a non-standard use of the `Range` header, there are examples of [similar approaches](https://developers.google.c om/youtube/v3/guides/using_resumable_upload_protocol) in APIs with heavy use. For an upload that just started, for an example with a 1000 byte layer file, the `Range` header would be as follows: ``` Range: bytes=0-0 ``` To get the status of an upload, issue a GET request to the upload URL: ``` GET /v2//blobs/uploads/ Host: ``` The response will be similar to the above, except will return 204 status: ``` 204 No Content Location: /v2//blobs/uploads/ Range: bytes=0- ``` Note that the HTTP `Range` header byte ranges are inclusive and that will be honored, even in non-standard use cases. ##### Monolithic Upload A monolithic upload is simply a chunked upload with a single chunk and may be favored by clients that would like to avoided the complexity of chunking. To carry out a "monolithic" upload, one can simply put the entire content blob to the provided URL: ``` PUT /v2//blobs/uploads/?digest=[&digest=sha256:] Content-Length: Content-Type: application/octet-stream ``` The "digest" parameter must be included with the PUT request. Please see the _Completed Upload_ section for details on the parameters and expected responses. Additionally, the download can be completed with a single `POST` request to the uploads endpoint, including the "size" and "digest" parameters: ``` POST /v2//blobs/uploads/?digest=[&digest=sha256:] Content-Length: Content-Type: application/octet-stream ``` On the registry service, this should allocate a download, accept and verify the data and return the same response as the final chunk of an upload. If the POST request fails collecting the data in any way, the registry should attempt to return an error response to the client with the `Location` header providing a place to continue the download. The single `POST` method is provided for convenience and most clients should implement `POST` + `PUT` to support reliable resume of uploads. ##### Chunked Upload To carry out an upload of a chunk, the client can specify a range header and only include that part of the layer file: ``` PATCH /v2//blobs/uploads/ Content-Length: Content-Range: - Content-Type: application/octet-stream ``` There is no enforcement on layer chunk splits other than that the server must receive them in order. The server may enforce a minimum chunk size. If the server cannot accept the chunk, a `416 Requested Range Not Satisfiable` response will be returned and will include a `Range` header indicating the current status: ``` 416 Requested Range Not Satisfiable Location: /v2//blobs/uploads/ Range: 0- Content-Length: 0 ``` If this response is received, the client should resume from the "last valid range" and upload the subsequent chunk. A 416 will be returned under the following conditions: - Invalid Content-Range header format - Out of order chunk: the range of the next chunk must start immediately after the "last valid range" from the previous response. When a chunk is accepted as part of the upload, a `202 Accepted` response will be returned, including a `Range` header with the current upload status: ``` 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- Content-Length: 0 ``` ##### Completed Upload For an upload to be considered complete, the client must submit a `PUT` request on the upload endpoint with a digest parameter. If it is not provided, the download will not be considered complete. The format for the final chunk will be as follows: ``` PUT /v2//blob/uploads/?digest=[&digest=sha256:] Content-Length: Content-Range: - Content-Type: application/octet-stream ``` Optionally, if all chunks have already been uploaded, a `PUT` request with a `digest` parameter and zero-length body may be sent to complete and validated the upload. Multiple "digest" parameters may be provided with different digests. The server may verify none or all of them but _must_ notify the client if the content is rejected. When the last chunk is received and the layer has been validated, the client will receive a `201 Created` response: ``` 201 Created Location: /v2//blobs/ Content-Length: 0 ``` The `Location` header will contain the registry URL to access the accepted layer file. ###### Digest Parameter The "digest" parameter is designed as an opaque parameter to support verification of a successful transfer. The initial version of the registry API will support a tarsum digest, in the standard tarsum format. For example, a HTTP URI parameter might be as follows: ``` tarsum.v1+sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b ``` Given this parameter, the registry will verify that the provided content does result in this tarsum. Optionally, the registry can support other other digest parameters for non-tarfile content stored as a layer. A regular hash digest might be specified as follows: ``` sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b ``` Such a parameter would be used to verify that the binary content (as opposed to the tar content) would be verified at the end of the upload process. For the initial version, registry servers are only required to support the tarsum format. ##### Canceling an Upload An upload can be cancelled by issuing a DELETE request to the upload endpoint. The format will be as follows: ``` DELETE /v2//blobs/uploads/ ``` After this request is issued, the upload uuid will no longer be valid and the registry server will dump all intermediate data. While uploads will time out if not completed, clients should issue this request if they encounter a fatal error but still have the ability to issue an http request. ##### Errors If an 502, 503 or 504 error is received, the client should assume that the download can proceed due to a temporary condition, honoring the appropriate retry mechanism. Other 5xx errors should be treated as terminal. If there is a problem with the upload, a 4xx error will be returned indicating the problem. After receiving a 4xx response (except 416, as called out above), the upload will be considered failed and the client should take appropriate action. Note that the upload url will not be available forever. If the upload uuid is unknown to the registry, a `404 Not Found` response will be returned and the client must restart the upload process. #### Pushing an Image Manifest Once all of the layers for an image are uploaded, the client can upload the image manifest. An image can be pushed using the following request format: PUT /v2//manifests/ { "name": , "tag": , "fsLayers": [ { "blobSum": }, ... ] ], "history": , "signature": , ... } The `name` and `tag` fields of the response body must match those specified in the URL. If there is a problem with pushing the manifest, a relevant 4xx response will be returned with a JSON error message. Please see the _PUT Manifest section for details on possible error codes that may be returned. If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are returned. The `detail` field of the error response will have a `digest` field identifying the missing blob, which will be a tarsum. An error is returned for each unknown blob. The response format is as follows: { "errors:" [{ "code": "BLOB_UNKNOWN", "message": "blob unknown to registry", "detail": { "digest": } }, ... ] } #### Listing Image Tags It may be necessary to list all of the tags under a given repository. The tags for an image repository can be retrieved with the following request: GET /v2//tags/list The response will be in the following format: 200 OK Content-Type: application/json { "name": , "tags": [ , ... ] } For repositories with a large number of tags, this response may be quite large, so care should be taken by the client when parsing the response to reduce copying. ### Deleting an Image An image may be deleted from the registry via its `name` and `tag`. A delete may be issued with the following request format: DELETE /v2//manifests/ If the image exists and has been successfully deleted, the following response will be issued: 202 Accepted Content-Length: None If the image had already been deleted or did not exist, a `404 Not Found` response will be issued instead. ## Detail > **Note**: This section is still under construction. For the purposes of > implementation, if any details below differ from the described request flows > above, the section below should be corrected. When they match, this note > should be removed. The behavior of the endpoints are covered in detail in this section, organized by route and entity. All aspects of the request and responses are covered, including headers, parameters and body formats. Examples of requests and their corresponding responses, with success and failure, are enumerated. > **Note**: The sections on endpoint detail are arranged with an example > request, a description of the request, followed by information about that > request. A list of methods and URIs are covered in the table below: |Method|Path|Entity|Description| -------|----|------|------------ {{range $route := .RouteDescriptors}}{{range $method := .Methods}}| {{$method.Method}} | `{{$route.Path|prettygorilla}}` | {{$route.Entity}} | {{$method.Description}} | {{end}}{{end}} The detail for each endpoint is covered in the following sections. ### Errors The error codes encountered via the API are enumerated in the following table: |Code|Message|Description| -------|----|------|------------ {{range $err := .ErrorDescriptors}} `{{$err.Value}}` | {{$err.Message}} | {{$err.Description|removenewlines}} {{end}} {{range $route := .RouteDescriptors}} ### {{.Entity}} {{.Description}} {{range $method := $route.Methods}} #### {{.Method}} {{$route.Entity}} {{.Description}} {{if .Requests}}{{range .Requests}}{{if .Name}} ##### {{.Name}}{{end}} ``` {{$method.Method}} {{$route.Path|prettygorilla}}{{if .QueryParameters}}?{{range .QueryParameters}}{{.Name}}={{.Format}}{{end}}{{end}}{{range .Headers}} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` {{.Description}} {{if or .Headers .PathParameters .QueryParameters}} The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| {{range .Headers}}|`{{.Name}}`|header|{{.Description}}| {{end}}{{range .PathParameters}}|`{{.Name}}`|path|{{.Description}}| {{end}}{{range .QueryParameters}}|`{{.Name}}`|query|{{.Description}}| {{end}}{{end}} {{if .Successes}} {{range .Successes}} ###### On Success: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}} ``` {{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` {{.Description}} {{if .Headers}}The following headers will be returned with the response: |Name|Description| |----|-----------| {{range .Headers}}|`{{.Name}}`|{{.Description}}| {{end}}{{end}}{{end}}{{end}} {{if .Failures}} {{range .Failures}} ###### On Failure: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}} ``` {{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` {{.Description}} {{if .Headers}} The following headers will be returned on the response: |Name|Description| |----|-----------| {{range .Headers}}|`{{.Name}}`|{{.Description}}| {{end}}{{end}} {{if .ErrorCodes}} The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ {{range $err := .ErrorCodes}}| `{{$err}}` | {{$err.Descriptor.Message}} | {{$err.Descriptor.Description|removenewlines}} | {{end}} {{end}}{{end}}{{end}}{{end}}{{end}}{{end}} {{end}}