From 83b899dab6c9a7b0df85898d17fb8d7520090149 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Tue, 30 Dec 2014 20:07:37 -0800 Subject: [PATCH 1/6] Add blob upload invalid error code --- api/v2/descriptors.go | 8 ++++++++ api/v2/errors.go | 3 +++ doc/SPEC.md | 1 + 3 files changed, 12 insertions(+) diff --git a/api/v2/descriptors.go b/api/v2/descriptors.go index dfbbc6f90..1ee5471ee 100644 --- a/api/v2/descriptors.go +++ b/api/v2/descriptors.go @@ -977,6 +977,14 @@ var errorDescriptors = []ErrorDescriptor{ started, this error code may be returned.`, HTTPStatusCodes: []int{http.StatusNotFound}, }, + { + Code: ErrorCodeBlobUploadInvalid, + Value: "BLOB_UPLOAD_INVALID", + Message: "blob upload invalid", + Description: `The blob upload encountered an error and can no + longer proceed.`, + HTTPStatusCodes: []int{http.StatusNotFound}, + }, } var errorCodeToDescriptors map[ErrorCode]ErrorDescriptor diff --git a/api/v2/errors.go b/api/v2/errors.go index 94c646fc8..4d5d55c7a 100644 --- a/api/v2/errors.go +++ b/api/v2/errors.go @@ -54,6 +54,9 @@ const ( // ErrorCodeBlobUploadUnknown is returned when an upload is unknown. ErrorCodeBlobUploadUnknown + + // ErrorCodeBlobUploadInvalid is returned when an upload is invalid. + ErrorCodeBlobUploadInvalid ) // ParseErrorCode attempts to parse the error code string, returning diff --git a/doc/SPEC.md b/doc/SPEC.md index 13b510e3d..ebf4958e8 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -703,6 +703,7 @@ The error codes encountered via the API are enumerated in the following table: `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. + `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. From 71819ac9c3cb76bd87383c5840cf8517a2f8f535 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Tue, 30 Dec 2014 20:09:45 -0800 Subject: [PATCH 2/6] Use full json content type with charset parameter --- api_test.go | 4 ++-- app.go | 6 +++--- app_test.go | 4 ++-- helpers.go | 2 +- images.go | 2 +- tags.go | 2 ++ 6 files changed, 11 insertions(+), 9 deletions(-) diff --git a/api_test.go b/api_test.go index 76c3b3484..3db3a4d4a 100644 --- a/api_test.go +++ b/api_test.go @@ -53,7 +53,7 @@ func TestCheckAPI(t *testing.T) { checkResponse(t, "issuing api base check", resp, http.StatusOK) checkHeaders(t, resp, http.Header{ - "Content-Type": []string{"application/json"}, + "Content-Type": []string{"application/json; charset=utf-8"}, "Content-Length": []string{"2"}, }) @@ -221,7 +221,7 @@ func TestManifestAPI(t *testing.T) { // TODO(stevvooe): Shoot. The error setup is not working out. The content- // type headers are being set after writing the status code. - // if resp.Header.Get("Content-Type") != "application/json" { + // if resp.Header.Get("Content-Type") != "application/json; charset=utf-8" { // t.Fatalf("unexpected content type: %v != 'application/json'", // resp.Header.Get("Content-Type")) // } diff --git a/app.go b/app.go index d8276ceca..13781b786 100644 --- a/app.go +++ b/app.go @@ -215,7 +215,7 @@ func (app *App) authorized(w http.ResponseWriter, r *http.Request, context *Cont // under which name is not set and we still allow access is when the // base route is accessed. This section prevents us from making that // mistake elsewhere in the code, allowing any operation to proceed. - w.Header().Set("Content-Type", "application/json") + w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(http.StatusForbidden) var errs v2.Errors @@ -227,7 +227,7 @@ func (app *App) authorized(w http.ResponseWriter, r *http.Request, context *Cont if err := app.accessController.Authorized(r, accessRecords...); err != nil { switch err := err.(type) { case auth.Challenge: - w.Header().Set("Content-Type", "application/json") + w.Header().Set("Content-Type", "application/json; charset=utf-8") err.ServeHTTP(w, r) var errs v2.Errors @@ -253,7 +253,7 @@ func (app *App) authorized(w http.ResponseWriter, r *http.Request, context *Cont func apiBase(w http.ResponseWriter, r *http.Request) { const emptyJSON = "{}" // Provide a simple /v2/ 200 OK response with empty json response. - w.Header().Set("Content-Type", "application/json") + w.Header().Set("Content-Type", "application/json; charset=utf-8") w.Header().Set("Content-Length", fmt.Sprint(len(emptyJSON))) fmt.Fprint(w, emptyJSON) diff --git a/app_test.go b/app_test.go index d3d6d9798..4d9535f74 100644 --- a/app_test.go +++ b/app_test.go @@ -173,8 +173,8 @@ func TestNewApp(t *testing.T) { t.Fatalf("unexpected status code during request: %v", err) } - if req.Header.Get("Content-Type") != "application/json" { - t.Fatalf("unexpected content-type: %v != %v", req.Header.Get("Content-Type"), "application/json") + if req.Header.Get("Content-Type") != "application/json; charset=utf-8" { + t.Fatalf("unexpected content-type: %v != %v", req.Header.Get("Content-Type"), "application/json; charset=utf-8") } expectedAuthHeader := "Bearer realm=\"realm-test\",service=\"service-test\"" diff --git a/helpers.go b/helpers.go index 6fce84a2f..6bcb4ae82 100644 --- a/helpers.go +++ b/helpers.go @@ -10,7 +10,7 @@ import ( // 'application/json'. If a different status code is required, call // ResponseWriter.WriteHeader before this function. func serveJSON(w http.ResponseWriter, v interface{}) error { - w.Header().Set("Content-Type", "application/json") + w.Header().Set("Content-Type", "application/json; charset=utf-8") enc := json.NewEncoder(w) if err := enc.Encode(v); err != nil { diff --git a/images.go b/images.go index 6a9721091..dbe1c3aed 100644 --- a/images.go +++ b/images.go @@ -46,7 +46,7 @@ func (imh *imageManifestHandler) GetImageManifest(w http.ResponseWriter, r *http return } - w.Header().Set("Content-Type", "application/json") + w.Header().Set("Content-Type", "application/json; charset=utf-8") w.Header().Set("Content-Length", fmt.Sprint(len(manifest.Raw))) w.Write(manifest.Raw) } diff --git a/tags.go b/tags.go index 458e6d1a1..18f6add21 100644 --- a/tags.go +++ b/tags.go @@ -47,6 +47,8 @@ func (th *tagsHandler) GetTags(w http.ResponseWriter, r *http.Request) { return } + w.Header().Set("Content-Type", "application/json; charset=utf-8") + enc := json.NewEncoder(w) if err := enc.Encode(tagsAPIResponse{ Name: th.Name, From 80816100e214817e87780ba05ad90098c7168796 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Tue, 30 Dec 2014 20:11:04 -0800 Subject: [PATCH 3/6] Fill in API detail in RouteDescriptors This changeset fills in details for many RouteDescriptors, ensuring that responses and their variation are fully covered. At this point, all endpoints are described in full. Tweaks for consistency and to avoid repetition may still need to be done. Signed-off-by: Stephen J Day --- api/v2/descriptors.go | 559 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 491 insertions(+), 68 deletions(-) diff --git a/api/v2/descriptors.go b/api/v2/descriptors.go index 1ee5471ee..22ef32a03 100644 --- a/api/v2/descriptors.go +++ b/api/v2/descriptors.go @@ -40,10 +40,18 @@ var ( Description: `Digest of desired blob.`, } + hostHeader = ParameterDescriptor{ + Name: "Host", + Type: "string", + Description: "Standard HTTP Host Header. Should be set to the registry host.", + Format: "", + Examples: []string{"registry-1.docker.io"}, + } + authHeader = ParameterDescriptor{ Name: "Authorization", Type: "string", - Description: "rfc7235 compliant authorization header.", + Description: "An RFC7235 compliant authorization header.", Format: " ", Examples: []string{"Bearer dGhpcyBpcyBhIGZha2UgYmVhcmVyIHRva2VuIQ=="}, } @@ -64,6 +72,48 @@ var ( Type: "integer", Format: "0", } + + unauthorizedResponse = ResponseDescriptor{ + Description: "The client does not have access to the repository.", + StatusCode: http.StatusUnauthorized, + Headers: []ParameterDescriptor{ + authChallengeHeader, + { + Name: "Content-Length", + Type: "integer", + Description: "Length of the JSON error response body.", + Format: "", + }, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: unauthorizedErrorsBody, + }, + } + + unauthorizedResponsePush = ResponseDescriptor{ + Description: "The client does not have access to push to the repository.", + StatusCode: http.StatusUnauthorized, + Headers: []ParameterDescriptor{ + authChallengeHeader, + { + Name: "Content-Length", + Type: "integer", + Description: "Length of the JSON error response body.", + Format: "", + }, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: unauthorizedErrorsBody, + }, + } ) const ( @@ -82,7 +132,8 @@ const ( }` errorsBody = `{ - "errors:" [{ + "errors:" [ + { "code": , "message": "", "detail": ... @@ -90,6 +141,17 @@ const ( ... ] }` + + unauthorizedErrorsBody = `{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +}` ) // APIDescriptor exports descriptions of the layout of the v2 registry API. @@ -279,6 +341,7 @@ var routeDescriptors = []RouteDescriptor{ Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ + hostHeader, authHeader, }, Successes: []ResponseDescriptor{ @@ -294,6 +357,13 @@ var routeDescriptors = []RouteDescriptor{ Headers: []ParameterDescriptor{ authChallengeHeader, }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, }, { Description: "The registry does not implement the V2 API.", @@ -316,6 +386,10 @@ var routeDescriptors = []RouteDescriptor{ Description: "Fetch the tags under the repository identified by `name`.", Requests: []RequestDescriptor{ { + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, }, @@ -323,8 +397,16 @@ var routeDescriptors = []RouteDescriptor{ { StatusCode: http.StatusOK, Description: "A list of tags for the named repository.", + Headers: []ParameterDescriptor{ + { + Name: "Content-Length", + Type: "integer", + Description: "Length of the JSON response body.", + Format: "", + }, + }, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: `{ "name": , "tags": [ @@ -339,10 +421,24 @@ var routeDescriptors = []RouteDescriptor{ { StatusCode: http.StatusNotFound, Description: "The repository is not known to the registry.", + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeNameUnknown, + }, }, { StatusCode: http.StatusUnauthorized, - Description: "The client doesn't have access to repository.", + Description: "The client does not have access to the repository.", + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, }, }, }, @@ -361,16 +457,20 @@ var routeDescriptors = []RouteDescriptor{ Description: "Fetch the manifest identified by `name` and `tag`.", Requests: []RequestDescriptor{ { + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, tagParameterDescriptor, }, Successes: []ResponseDescriptor{ { - Description: "The manifest idenfied by `name` and `tag`.", + Description: "The manifest idenfied by `name` and `tag`. The contents can be used to identify and resolve resources required to run the specified image.", StatusCode: http.StatusOK, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: manifestBody, }, }, @@ -384,10 +484,21 @@ var routeDescriptors = []RouteDescriptor{ ErrorCodeTagInvalid, }, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: errorsBody, }, }, + { + StatusCode: http.StatusUnauthorized, + Description: "The client does not have access to the repository.", + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + }, { Description: "The named manifest is not known to the registry.", StatusCode: http.StatusNotFound, @@ -396,7 +507,7 @@ var routeDescriptors = []RouteDescriptor{ ErrorCodeManifestUnknown, }, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: errorsBody, }, }, @@ -410,6 +521,7 @@ var routeDescriptors = []RouteDescriptor{ Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ + hostHeader, authHeader, }, PathParameters: []ParameterDescriptor{ @@ -417,17 +529,33 @@ var routeDescriptors = []RouteDescriptor{ tagParameterDescriptor, }, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: manifestBody, }, Successes: []ResponseDescriptor{ { - StatusCode: http.StatusAccepted, + Description: "The manifest has been accepted by the registry and is stored under the specified `name` and `tag`.", + StatusCode: http.StatusAccepted, + Headers: []ParameterDescriptor{ + { + Name: "Location", + Type: "url", + Description: "The canonical location url of the uploaded manifest.", + Format: "", + }, + contentLengthZeroHeader, + }, }, }, Failures: []ResponseDescriptor{ { - StatusCode: http.StatusBadRequest, + Name: "Invalid Manifest", + Description: "The recieved manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.", + StatusCode: http.StatusBadRequest, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, ErrorCodes: []ErrorCode{ ErrorCodeNameInvalid, ErrorCodeTagInvalid, @@ -437,13 +565,25 @@ var routeDescriptors = []RouteDescriptor{ }, }, { + StatusCode: http.StatusUnauthorized, + Description: "The client does not have permission to push to the repository.", + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + }, + { + Name: "Missing Layer(s)", Description: "One or more layers may be missing during a manifest upload. If so, the missing layers will be enumerated in the error response.", StatusCode: http.StatusBadRequest, ErrorCodes: []ErrorCode{ ErrorCodeBlobUnknown, }, Body: BodyDescriptor{ - ContentType: "application/json", + ContentType: "application/json; charset=utf-8", Format: `{ "errors:" [{ "code": "BLOB_UNKNOWN", @@ -461,6 +601,19 @@ var routeDescriptors = []RouteDescriptor{ StatusCode: http.StatusUnauthorized, Headers: []ParameterDescriptor{ authChallengeHeader, + { + Name: "Content-Length", + Type: "integer", + Description: "Length of the JSON error response body.", + Format: "", + }, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, }, }, }, @@ -473,6 +626,7 @@ var routeDescriptors = []RouteDescriptor{ Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ + hostHeader, authHeader, }, PathParameters: []ParameterDescriptor{ @@ -486,24 +640,49 @@ var routeDescriptors = []RouteDescriptor{ }, Failures: []ResponseDescriptor{ { - StatusCode: http.StatusBadRequest, + Name: "Invalid Name or Tag", + Description: "The specified `name` or `tag` were invalid and the delete was unable to proceed.", + StatusCode: http.StatusBadRequest, ErrorCodes: []ErrorCode{ ErrorCodeNameInvalid, ErrorCodeTagInvalid, }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, }, { StatusCode: http.StatusUnauthorized, Headers: []ParameterDescriptor{ authChallengeHeader, + { + Name: "Content-Length", + Type: "integer", + Description: "Length of the JSON error response body.", + Format: "", + }, + }, + ErrorCodes: []ErrorCode{ + ErrorCodeUnauthorized, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, }, }, { - StatusCode: http.StatusNotFound, + Name: "Unknown Manifest", + Description: "The specified `name` or `tag` are unknown to the registry and the delete was unable to proceed. Clients can assume the manifest was already deleted if this response is returned.", + StatusCode: http.StatusNotFound, ErrorCodes: []ErrorCode{ ErrorCodeNameUnknown, ErrorCodeManifestUnknown, }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, }, }, }, @@ -521,9 +700,14 @@ var routeDescriptors = []RouteDescriptor{ { Method: "GET", - Description: "Retrieve the blob from the registry identified by `digest`.", + Description: "Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data.", Requests: []RequestDescriptor{ { + Name: "Fetch Blob", + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, digestPathParameter, @@ -532,6 +716,14 @@ var routeDescriptors = []RouteDescriptor{ { Description: "The blob identified by `digest` is available. The blob content will be present in the body of the request.", StatusCode: http.StatusOK, + Headers: []ParameterDescriptor{ + { + Name: "Content-Length", + Type: "integer", + Description: "The length of the requested blob content.", + Format: "", + }, + }, Body: BodyDescriptor{ ContentType: "application/octet-stream", Format: "", @@ -552,17 +744,25 @@ var routeDescriptors = []RouteDescriptor{ }, Failures: []ResponseDescriptor{ { - StatusCode: http.StatusBadRequest, + Description: "There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.", + StatusCode: http.StatusBadRequest, ErrorCodes: []ErrorCode{ ErrorCodeNameInvalid, ErrorCodeDigestInvalid, }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, }, + unauthorizedResponse, { - StatusCode: http.StatusUnauthorized, - }, - { - StatusCode: http.StatusNotFound, + Description: "The blob, identified by `name` and `digest`, is unknown to the registry.", + StatusCode: http.StatusNotFound, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, ErrorCodes: []ErrorCode{ ErrorCodeNameUnknown, ErrorCodeBlobUnknown, @@ -570,17 +770,77 @@ var routeDescriptors = []RouteDescriptor{ }, }, }, - }, - }, - { - Method: "HEAD", - Description: "Check if the blob is known to the registry.", - Requests: []RequestDescriptor{ { + Name: "Fetch Blob Part", + Description: "This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content.", + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + { + Name: "Range", + Type: "string", + Description: "HTTP Range header specifying blob chunk.", + Format: "bytes=-", + }, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, digestPathParameter, }, + Successes: []ResponseDescriptor{ + { + Description: "The blob identified by `digest` is available. The specified chunk of blob content will be present in the body of the request.", + StatusCode: http.StatusPartialContent, + Headers: []ParameterDescriptor{ + { + Name: "Content-Length", + Type: "integer", + Description: "The length of the requested blob chunk.", + Format: "", + }, + { + Name: "Content-Range", + Type: "byte range", + Description: "Content range of blob chunk.", + Format: "bytes -/", + }, + }, + Body: BodyDescriptor{ + ContentType: "application/octet-stream", + Format: "", + }, + }, + }, + Failures: []ResponseDescriptor{ + { + Description: "There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeNameInvalid, + ErrorCodeDigestInvalid, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + unauthorizedResponse, + { + StatusCode: http.StatusNotFound, + ErrorCodes: []ErrorCode{ + ErrorCodeNameUnknown, + ErrorCodeBlobUnknown, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + { + Description: "The range specification cannot be satisfied for the requested content. This can happen when the range is not formatted correctly or if the range is outside of the valid size of the content.", + StatusCode: http.StatusRequestedRangeNotSatisfiable, + }, + }, }, }, }, @@ -604,6 +864,7 @@ var routeDescriptors = []RouteDescriptor{ Name: "Initiate Monolithic Blob Upload", Description: "Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned.", Headers: []ParameterDescriptor{ + hostHeader, authHeader, { Name: "Content-Length", @@ -629,7 +890,8 @@ var routeDescriptors = []RouteDescriptor{ }, Successes: []ResponseDescriptor{ { - StatusCode: http.StatusCreated, + Description: "The blob has been created in the registry and is available the provided location.", + StatusCode: http.StatusCreated, Headers: []ParameterDescriptor{ { Name: "Location", @@ -649,23 +911,14 @@ var routeDescriptors = []RouteDescriptor{ ErrorCodeNameInvalid, }, }, - { - Name: "Unauthorized", - StatusCode: http.StatusUnauthorized, - Headers: []ParameterDescriptor{ - authChallengeHeader, - }, - ErrorCodes: []ErrorCode{ - ErrorCodeDigestInvalid, - ErrorCodeNameInvalid, - }, - }, + unauthorizedResponsePush, }, }, { Name: "Initiate Resumable Blob Upload", Description: "Initiate a resumable blob upload with an empty request body.", Headers: []ParameterDescriptor{ + hostHeader, authHeader, contentLengthZeroHeader, }, @@ -674,7 +927,7 @@ var routeDescriptors = []RouteDescriptor{ }, Successes: []ResponseDescriptor{ { - Description: "The upload has been created. The `Location` header must be used to complete the upload. The response should identical to a `GET` request on the contents of the returned `Location` header.", + Description: "The upload has been created. The `Location` header must be used to complete the upload. The response should be identical to a `GET` request on the contents of the returned `Location` header.", StatusCode: http.StatusAccepted, Headers: []ParameterDescriptor{ contentLengthZeroHeader, @@ -692,6 +945,17 @@ var routeDescriptors = []RouteDescriptor{ }, }, }, + Failures: []ResponseDescriptor{ + { + Name: "Invalid Name or Digest", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeDigestInvalid, + ErrorCodeNameInvalid, + }, + }, + unauthorizedResponsePush, + }, }, }, }, @@ -702,7 +966,7 @@ var routeDescriptors = []RouteDescriptor{ Name: RouteNameBlobUploadChunk, Path: "/v2/{name:" + common.RepositoryNameRegexp.String() + "}/blobs/uploads/{uuid}", Entity: "Blob Upload", - Description: "Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests.", + Description: "Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. The `Location` header and its parameters should be preserved by clients, using the latest value returned via upload related API calls.", Methods: []MethodDescriptor{ { Method: "GET", @@ -710,13 +974,19 @@ var routeDescriptors = []RouteDescriptor{ Requests: []RequestDescriptor{ { Description: "Retrieve the progress of the current upload, as reported by the `Range` header.", + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, uuidParameterDescriptor, }, Successes: []ResponseDescriptor{ { - StatusCode: http.StatusNoContent, + Name: "Upload Progress", + Description: "The upload is known and in progress. The last received offset is available in the `Range` header.", + StatusCode: http.StatusNoContent, Headers: []ParameterDescriptor{ { Name: "Range", @@ -724,32 +994,34 @@ var routeDescriptors = []RouteDescriptor{ Format: "0-", Description: "Range indicating the current progress of the upload.", }, + contentLengthZeroHeader, }, }, }, - }, - }, - }, - { - Method: "HEAD", - Description: "Retrieve status of upload identified by `uuid`. This is identical to the GET request.", - Requests: []RequestDescriptor{ - { - Description: "Retrieve the progress of the current upload, as reported by the `Range` header.", - PathParameters: []ParameterDescriptor{ - nameParameterDescriptor, - uuidParameterDescriptor, - }, - Successes: []ResponseDescriptor{ + Failures: []ResponseDescriptor{ { - StatusCode: http.StatusNoContent, - Headers: []ParameterDescriptor{ - { - Name: "Range", - Type: "header", - Format: "0-", - Description: "Range indicating the current progress of the upload.", - }, + Description: "There was an error processing the upload and it must be restarted.", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeDigestInvalid, + ErrorCodeNameInvalid, + ErrorCodeBlobUploadInvalid, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + unauthorizedResponse, + { + Description: "The upload is unknown to the registry. The upload must be restarted.", + StatusCode: http.StatusNotFound, + ErrorCodes: []ErrorCode{ + ErrorCodeBlobUploadUnknown, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, }, }, }, @@ -767,6 +1039,8 @@ var routeDescriptors = []RouteDescriptor{ uuidParameterDescriptor, }, Headers: []ParameterDescriptor{ + hostHeader, + authHeader, { Name: "Content-Range", Type: "header", @@ -787,8 +1061,16 @@ var routeDescriptors = []RouteDescriptor{ }, Successes: []ResponseDescriptor{ { - StatusCode: http.StatusNoContent, + Name: "Chunk Accepted", + Description: "The chunk of data has been accepted and the current progress is available in the range header. The updated upload location is available in the `Location` header.", + StatusCode: http.StatusNoContent, Headers: []ParameterDescriptor{ + { + Name: "Location", + Type: "url", + Format: "/v2//blobs/uploads/", + Description: "The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.", + }, { Name: "Range", Type: "header", @@ -799,6 +1081,37 @@ var routeDescriptors = []RouteDescriptor{ }, }, }, + Failures: []ResponseDescriptor{ + { + Description: "There was an error processing the upload and it must be restarted.", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeDigestInvalid, + ErrorCodeNameInvalid, + ErrorCodeBlobUploadInvalid, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + unauthorizedResponsePush, + { + Description: "The upload is unknown to the registry. The upload must be restarted.", + StatusCode: http.StatusNotFound, + ErrorCodes: []ErrorCode{ + ErrorCodeBlobUploadUnknown, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + { + Description: "The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid.", + StatusCode: http.StatusRequestedRangeNotSatisfiable, + }, + }, }, }, }, @@ -812,7 +1125,23 @@ var routeDescriptors = []RouteDescriptor{ // 2. Complete an upload where the entire body is in the PUT. // 3. Complete an upload where the final, partial chunk is the body. - Description: "Upload the _final_ chunk of data.", + Description: "Complete the upload, providing the _final_ chunk of data, if necessary. This method may take a body with all the data. If the `Content-Range` header is specified, it may include the final chunk. A request without a body will just complete the upload with previously uploaded content.", + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + { + Name: "Content-Range", + Type: "header", + Format: "-", + Description: "Range of bytes identifying the block of content represented by the body. Start must the end offset retrieved via status check plus one. Note that this is a non-standard use of the `Content-Range` header. May be omitted if no data is provided.", + }, + { + Name: "Content-Length", + Type: "integer", + Format: "", + Description: "Length of the chunk being uploaded, corresponding to the length of the request body. May be zero if no data is provided.", + }, + }, PathParameters: []ParameterDescriptor{ nameParameterDescriptor, uuidParameterDescriptor, @@ -827,10 +1156,21 @@ var routeDescriptors = []RouteDescriptor{ Description: `Digest of uploaded blob.`, }, }, + Body: BodyDescriptor{ + ContentType: "application/octet-stream", + Format: "", + }, Successes: []ResponseDescriptor{ { - StatusCode: http.StatusNoContent, + Name: "Upload Complete", + Description: "The upload has been completed and accepted by the registry. The canonical location will be available in the `Location` header.", + StatusCode: http.StatusNoContent, Headers: []ParameterDescriptor{ + { + Name: "Location", + Type: "url", + Format: "", + }, { Name: "Content-Range", Type: "header", @@ -844,9 +1184,50 @@ var routeDescriptors = []RouteDescriptor{ Description: "Length of the chunk being uploaded, corresponding the length of the request body.", }, }, + }, + }, + Failures: []ResponseDescriptor{ + { + Description: "There was an error processing the upload and it must be restarted.", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeDigestInvalid, + ErrorCodeNameInvalid, + ErrorCodeBlobUploadInvalid, + }, Body: BodyDescriptor{ - ContentType: "application/octet-stream", - Format: "", + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + unauthorizedResponsePush, + { + Description: "The upload is unknown to the registry. The upload must be restarted.", + StatusCode: http.StatusNotFound, + ErrorCodes: []ErrorCode{ + ErrorCodeBlobUploadUnknown, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + { + Description: "The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid. The contents of the `Range` header may be used to resolve the condition.", + StatusCode: http.StatusRequestedRangeNotSatisfiable, + Headers: []ParameterDescriptor{ + { + Name: "Location", + Type: "url", + Format: "/v2//blobs/uploads/", + Description: "The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.", + }, + { + Name: "Range", + Type: "header", + Format: "0-", + Description: "Range indicating the current progress of the upload.", + }, }, }, }, @@ -863,6 +1244,48 @@ var routeDescriptors = []RouteDescriptor{ nameParameterDescriptor, uuidParameterDescriptor, }, + Headers: []ParameterDescriptor{ + hostHeader, + authHeader, + contentLengthZeroHeader, + }, + Successes: []ResponseDescriptor{ + { + Name: "Upload Deleted", + Description: "The upload has been successfully deleted.", + StatusCode: http.StatusNoContent, + Headers: []ParameterDescriptor{ + contentLengthZeroHeader, + }, + }, + }, + Failures: []ResponseDescriptor{ + { + Description: "An error was encountered processing the delete. The client may ignore this error.", + StatusCode: http.StatusBadRequest, + ErrorCodes: []ErrorCode{ + ErrorCodeDigestInvalid, + ErrorCodeNameInvalid, + ErrorCodeBlobUploadInvalid, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + unauthorizedResponse, + { + Description: "The upload is unknown to the registry. The client may ignore this error and assume the upload has been deleted.", + StatusCode: http.StatusNotFound, + ErrorCodes: []ErrorCode{ + ErrorCodeBlobUploadUnknown, + }, + Body: BodyDescriptor{ + ContentType: "application/json; charset=utf-8", + Format: errorsBody, + }, + }, + }, }, }, }, From 977373912cc1a6d05105cbbc8e6dcf0b4d1a87c4 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Tue, 30 Dec 2014 20:15:02 -0800 Subject: [PATCH 4/6] Tweak template output whitespace around descriptions Signed-off-by: Stephen J Day --- doc/SPEC.md.tmpl | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/SPEC.md.tmpl b/doc/SPEC.md.tmpl index 5d3bdebcb..b9840a17e 100644 --- a/doc/SPEC.md.tmpl +++ b/doc/SPEC.md.tmpl @@ -693,8 +693,8 @@ The error codes encountered via the API are enumerated in the following table: {{.Description}} -{{if .Requests}}{{range .Requests}} -##### {{.Name}} +{{if .Requests}}{{range .Requests}}{{if .Name}} +##### {{.Name}}{{end}} ``` {{$method.Method}} {{$route.Path|prettygorilla}}{{if .QueryParameters}}?{{range .QueryParameters}}{{.Name}}={{.Format}}{{end}}{{end}}{{range .Headers}} @@ -728,8 +728,9 @@ Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` -{{.Description}}{{if .Headers}} -The following headers will be returned on the response: +{{.Description}} + +{{if .Headers}}The following headers will be returned with the response: |Name|Description| |----|-----------| From a882355dcd267ec041a5e8bef22aa772065c328d Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Tue, 30 Dec 2014 20:16:05 -0800 Subject: [PATCH 5/6] Regenerate V2 API Specification from template Many details have been updated in route descriptors. This commit regenerates the specification from the latest changes and template. Signed-off-by: Stephen J Day --- doc/SPEC.md | 1185 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 1067 insertions(+), 118 deletions(-) diff --git a/doc/SPEC.md b/doc/SPEC.md index ebf4958e8..f79989f4f 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -673,11 +673,9 @@ A list of methods and URIs are covered in the table below: | GET | `/v2//manifests/` | Manifest | Fetch the manifest identified by `name` and `tag`. | | PUT | `/v2//manifests/` | Manifest | Put the manifest identified by `name` and `tag`. | | DELETE | `/v2//manifests/` | Manifest | Delete the manifest identified by `name` and `tag`. | -| GET | `/v2//blobs/` | Blob | Retrieve the blob from the registry identified by `digest`. | -| HEAD | `/v2//blobs/` | Blob | Check if the blob is known to the registry. | +| GET | `/v2//blobs/` | Blob | Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. | | POST | `/v2//blobs/uploads/` | Intiate Blob Upload | Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request. | | GET | `/v2//blobs/uploads/` | Blob Upload | Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. | -| HEAD | `/v2//blobs/uploads/` | Blob Upload | Retrieve status of upload identified by `uuid`. This is identical to the GET request. | | PATCH | `/v2//blobs/uploads/` | Blob Upload | Upload a chunk of data for the specified upload. | | PUT | `/v2//blobs/uploads/` | Blob Upload | Complete the upload specified by `uuid`, optionally appending the body as the final chunk. | | DELETE | `/v2//blobs/uploads/` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. | @@ -718,10 +716,10 @@ Base V2 API route. Typically, this can be used for lightweight version checks an Check that the endpoint implements Docker Registry API V2. -##### ``` GET /v2/ +Host: Authorization: ``` @@ -732,7 +730,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| -|`Authorization`|header|rfc7235 compliant authorization header.| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| @@ -747,11 +746,25 @@ The API implements V2 protocol and is accessible. + + ###### On Failure: Unauthorized ``` 401 Unauthorized WWW-Authenticate: realm="", ..." +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` The client is not authorized to access the registry. @@ -764,6 +777,14 @@ The following headers will be returned on the response: +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + ###### On Failure: Not Found ``` @@ -787,10 +808,11 @@ Retrieve information about tags. Fetch the tags under the repository identified by `name`. -##### ``` GET /v2//tags/list +Host: +Authorization: ``` @@ -800,6 +822,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| @@ -809,7 +833,8 @@ The following parameters should be specified on the request: ``` 200 OK -Content-Type: application/json +Content-Length: +Content-Type: application/json; charset=utf-8 { "name": , @@ -822,25 +847,72 @@ Content-Type: application/json A list of tags for the named repository. +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Content-Length`|Length of the JSON response body.| + + ###### On Failure: Not Found ``` 404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` The repository is not known to the registry. +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | + + + ###### On Failure: Unauthorized ``` 401 Unauthorized +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` -The client doesn't have access to repository. +The client does not have access to the repository. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | @@ -857,10 +929,11 @@ Create, update and retrieve manifests. Fetch the manifest identified by `name` and `tag`. -##### ``` GET /v2//manifests/ +Host: +Authorization: ``` @@ -870,6 +943,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| |`tag`|path|Tag of the target manifiest.| @@ -880,7 +955,7 @@ The following parameters should be specified on the request: ``` 200 OK -Content-Type: application/json +Content-Type: application/json; charset=utf-8 { "name": , @@ -897,7 +972,9 @@ Content-Type: application/json } ``` -The manifest idenfied by `name` and `tag`. +The manifest idenfied by `name` and `tag`. The contents can be used to identify and resolve resources required to run the specified image. + + @@ -905,10 +982,11 @@ The manifest idenfied by `name` and `tag`. ``` 400 Bad Request -Content-Type: application/json +Content-Type: application/json; charset=utf-8 { - "errors:" [{ + "errors:" [ + { "code": , "message": "", "detail": ... @@ -931,14 +1009,45 @@ The error codes that may be included in the response body are enumerated below: +###### On Failure: Unauthorized + +``` +401 Unauthorized +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to the repository. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + ###### On Failure: Not Found ``` 404 Not Found -Content-Type: application/json +Content-Type: application/json; charset=utf-8 { - "errors:" [{ + "errors:" [ + { "code": , "message": "", "detail": ... @@ -967,12 +1076,12 @@ The error codes that may be included in the response body are enumerated below: Put the manifest identified by `name` and `tag`. -##### ``` PUT /v2//manifests/ +Host: Authorization: -Content-Type: application/json +Content-Type: application/json; charset=utf-8 { "name": , @@ -996,7 +1105,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| -|`Authorization`|header|rfc7235 compliant authorization header.| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| |`tag`|path|Tag of the target manifiest.| @@ -1007,19 +1117,41 @@ The following parameters should be specified on the request: ``` 202 Accepted +Location: +Content-Length: 0 ``` +The manifest has been accepted by the registry and is stored under the specified `name` and `tag`. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Location`|The canonical location url of the uploaded manifest.| +|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| -###### On Failure: Bad Request +###### On Failure: Invalid Manifest ``` 400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` - +The recieved manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request. @@ -1035,11 +1167,41 @@ The error codes that may be included in the response body are enumerated below: -###### On Failure: Bad Request +###### On Failure: Unauthorized + +``` +401 Unauthorized +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The client does not have permission to push to the repository. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Missing Layer(s) ``` 400 Bad Request -Content-Type: application/json +Content-Type: application/json; charset=utf-8 { "errors:" [{ @@ -1071,6 +1233,19 @@ The error codes that may be included in the response body are enumerated below: ``` 401 Unauthorized WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` @@ -1080,6 +1255,15 @@ The following headers will be returned on the response: |Name|Description| |----|-----------| |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | @@ -1089,10 +1273,10 @@ The following headers will be returned on the response: Delete the manifest identified by `name` and `tag`. -##### ``` DELETE /v2//manifests/ +Host: Authorization: ``` @@ -1103,7 +1287,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| -|`Authorization`|header|rfc7235 compliant authorization header.| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| |`tag`|path|Tag of the target manifiest.| @@ -1120,13 +1305,27 @@ The following parameters should be specified on the request: -###### On Failure: Bad Request + + +###### On Failure: Invalid Name or Tag ``` 400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` - +The specified `name` or `tag` were invalid and the delete was unable to proceed. @@ -1144,6 +1343,19 @@ The error codes that may be included in the response body are enumerated below: ``` 401 Unauthorized WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` @@ -1153,16 +1365,37 @@ The following headers will be returned on the response: |Name|Description| |----|-----------| |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| -###### On Failure: Not Found +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Unknown Manifest ``` 404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` - +The specified `name` or `tag` are unknown to the registry and the delete was unable to proceed. Clients can assume the manifest was already deleted if this response is returned. @@ -1185,13 +1418,15 @@ Fetch the blob identified by `name` and `digest`. Used to fetch layers by tarsum #### GET Blob -Retrieve the blob from the registry identified by `digest`. +Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. -##### +##### Fetch Blob ``` GET /v2//blobs/ +Host: +Authorization: ``` @@ -1201,6 +1436,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| |`digest`|path|Digest of desired blob.| @@ -1211,12 +1448,20 @@ The following parameters should be specified on the request: ``` 200 OK +Content-Length: Content-Type: application/octet-stream ``` The blob identified by `digest` is available. The blob content will be present in the body of the request. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Content-Length`|The length of the requested blob content.| + ###### On Success: Temporary Redirect ``` @@ -1225,7 +1470,8 @@ Location: ``` The blob identified by `digest` is available at the provided location. -The following headers will be returned on the response: + +The following headers will be returned with the response: |Name|Description| |----|-----------| @@ -1238,9 +1484,21 @@ The following headers will be returned on the response: ``` 400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` - +There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`. @@ -1257,9 +1515,38 @@ The error codes that may be included in the response body are enumerated below: ``` 401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} ``` +The client does not have access to the repository. +The following headers will be returned on the response: + +|Name|Description| +|----|-----------| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | @@ -1267,6 +1554,167 @@ The error codes that may be included in the response body are enumerated below: ``` 404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The blob, identified by `name` and `digest`, is unknown to the registry. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | +| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + + + +##### Fetch Blob Part + +``` +GET /v2//blobs/ +Host: +Authorization: +Range: bytes=- +``` + +This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content. + + +The following parameters should be specified on the request: + +|Name|Kind|Description| +|----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| +|`Range`|header|HTTP Range header specifying blob chunk.| +|`name`|path|Name of the target repository.| +|`digest`|path|Digest of desired blob.| + + + + +###### On Success: Partial Content + +``` +206 Partial Content +Content-Length: +Content-Range: bytes -/ +Content-Type: application/octet-stream + + +``` + +The blob identified by `digest` is available. The specified chunk of blob content will be present in the body of the request. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Content-Length`|The length of the requested blob chunk.| +|`Content-Range`|Content range of blob chunk.| + + + + +###### On Failure: Bad Request + +``` +400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to the repository. + +The following headers will be returned on the response: + +|Name|Description| +|----|-----------| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Not Found + +``` +404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` @@ -1282,29 +1730,13 @@ The error codes that may be included in the response body are enumerated below: - -#### HEAD Blob - -Check if the blob is known to the registry. - - -##### +###### On Failure: Requested Range Not Satisfiable ``` -HEAD /v2//blobs/ +416 Requested Range Not Satisfiable ``` - - - -The following parameters should be specified on the request: - -|Name|Kind|Description| -|----|----|-----------| -|`name`|path|Name of the target repository.| -|`digest`|path|Digest of desired blob.| - - +The range specification cannot be satisfied for the requested content. This can happen when the range is not formatted correctly or if the range is outside of the valid size of the content. @@ -1325,6 +1757,7 @@ Initiate a resumable blob upload. If successful, an upload location will be prov ``` POST /v2//blobs/uploads/?digest= +Host: Authorization: Content-Length: Content-Type: application/octect-stream @@ -1339,7 +1772,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| -|`Authorization`|header|rfc7235 compliant authorization header.| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`Content-Length`|header|| |`name`|path|Name of the target repository.| |`digest`|query|Digest of uploaded blob. If present, the upload will be completed, in a single request, with contents of the request body as the resulting blob.| @@ -1355,8 +1789,9 @@ Location: Content-Length: 0 ``` +The blob has been created in the registry and is available the provided location. -The following headers will be returned on the response: +The following headers will be returned with the response: |Name|Description| |----|-----------| @@ -1390,15 +1825,29 @@ The error codes that may be included in the response body are enumerated below: ``` 401 Unauthorized WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} ``` - +The client does not have access to push to the repository. The following headers will be returned on the response: |Name|Description| |----|-----------| |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| @@ -1406,8 +1855,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | @@ -1415,6 +1863,7 @@ The error codes that may be included in the response body are enumerated below: ``` POST /v2//blobs/uploads/ +Host: Authorization: Content-Length: 0 ``` @@ -1426,7 +1875,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| -|`Authorization`|header|rfc7235 compliant authorization header.| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.| |`name`|path|Name of the target repository.| @@ -1442,8 +1892,9 @@ Location: /v2//blobs/uploads/ Range: 0-0 ``` -The upload has been created. The `Location` header must be used to complete the upload. The response should identical to a `GET` request on the contents of the returned `Location` header. -The following headers will be returned on the response: +The upload has been created. The `Location` header must be used to complete the upload. The response should be identical to a `GET` request on the contents of the returned `Location` header. + +The following headers will be returned with the response: |Name|Description| |----|-----------| @@ -1454,10 +1905,69 @@ The following headers will be returned on the response: +###### On Failure: Invalid Name or Digest + +``` +400 Bad Request +``` + + + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to push to the repository. + +The following headers will be returned on the response: + +|Name|Description| +|----|-----------| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + + ### Blob Upload -Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. +Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. The `Location` header and its parameters should be preserved by clients, using the latest value returned via upload related API calls. @@ -1466,10 +1976,11 @@ Interact with blob uploads. Clients should never assemble URLs for this endpoint Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. -##### ``` GET /v2//blobs/uploads/ +Host: +Authorization: ``` Retrieve the progress of the current upload, as reported by the `Range` header. @@ -1479,66 +1990,132 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept almost anything.| -###### On Success: No Content +###### On Success: Upload Progress ``` 204 No Content Range: 0- +Content-Length: 0 ``` +The upload is known and in progress. The last received offset is available in the `Range` header. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Range`|Range indicating the current progress of the upload.| +|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| + + + + +###### On Failure: Bad Request + +``` +400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +There was an error processing the upload and it must be restarted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to the repository. The following headers will be returned on the response: |Name|Description| |----|-----------| -|`Range`|Range indicating the current progress of the upload.| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| +The error codes that may be included in the response body are enumerated below: -#### HEAD Blob Upload - -Retrieve status of upload identified by `uuid`. This is identical to the GET request. +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | -##### + +###### On Failure: Not Found ``` -HEAD /v2//blobs/uploads/ +404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} ``` -Retrieve the progress of the current upload, as reported by the `Range` header. - - -The following parameters should be specified on the request: - -|Name|Kind|Description| -|----|----|-----------| -|`name`|path|Name of the target repository.| -|`uuid`|path|A uuid identifying the upload. This field can accept almost anything.| +The upload is unknown to the registry. The upload must be restarted. +The error codes that may be included in the response body are enumerated below: -###### On Success: No Content - -``` -204 No Content -Range: 0- -``` - - -The following headers will be returned on the response: - -|Name|Description| -|----|-----------| -|`Range`|Range indicating the current progress of the upload.| +|Code|Message|Description| +-------|----|------|------------ +| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | @@ -1548,10 +2125,11 @@ The following headers will be returned on the response: Upload a chunk of data for the specified upload. -##### ``` PATCH /v2//blobs/uploads/ +Host: +Authorization: Content-Range: - Content-Length: Content-Type: application/octet-stream @@ -1566,6 +2144,8 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| |`Content-Range`|header|Range of bytes identifying the desired block of content represented by the body. Start must the end offset retrieved via status check plus one. Note that this is a non-standard use of the `Content-Range` header.| |`Content-Length`|header|Length of the chunk being uploaded, corresponding the length of the request body.| |`name`|path|Name of the target repository.| @@ -1574,21 +2154,136 @@ The following parameters should be specified on the request: -###### On Success: No Content +###### On Success: Chunk Accepted ``` 204 No Content +Location: /v2//blobs/uploads/ Range: 0- Content-Length: 0 ``` +The chunk of data has been accepted and the current progress is available in the range header. The updated upload location is available in the `Location` header. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Location`|The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.| +|`Range`|Range indicating the current progress of the upload.| +|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| + + + + +###### On Failure: Bad Request + +``` +400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +There was an error processing the upload and it must be restarted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to push to the repository. The following headers will be returned on the response: |Name|Description| |----|-----------| -|`Range`|Range indicating the current progress of the upload.| -|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Not Found + +``` +404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The upload is unknown to the registry. The upload must be restarted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + + + +###### On Failure: Requested Range Not Satisfiable + +``` +416 Requested Range Not Satisfiable +``` + +The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid. @@ -1598,30 +2293,11 @@ The following headers will be returned on the response: Complete the upload specified by `uuid`, optionally appending the body as the final chunk. -##### ``` PUT /v2//blobs/uploads/?digest= -``` - -Upload the _final_ chunk of data. - - -The following parameters should be specified on the request: - -|Name|Kind|Description| -|----|----|-----------| -|`name`|path|Name of the target repository.| -|`uuid`|path|A uuid identifying the upload. This field can accept almost anything.| -|`digest`|query|Digest of uploaded blob.| - - - - -###### On Success: No Content - -``` -204 No Content +Host: +Authorization: Content-Range: - Content-Length: Content-Type: application/octet-stream @@ -1629,13 +2305,163 @@ Content-Type: application/octet-stream ``` +Complete the upload, providing the _final_ chunk of data, if necessary. This method may take a body with all the data. If the `Content-Range` header is specified, it may include the final chunk. A request without a body will just complete the upload with previously uploaded content. + + +The following parameters should be specified on the request: + +|Name|Kind|Description| +|----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| +|`Content-Range`|header|Range of bytes identifying the block of content represented by the body. Start must the end offset retrieved via status check plus one. Note that this is a non-standard use of the `Content-Range` header. May be omitted if no data is provided.| +|`Content-Length`|header|Length of the chunk being uploaded, corresponding to the length of the request body. May be zero if no data is provided.| +|`name`|path|Name of the target repository.| +|`uuid`|path|A uuid identifying the upload. This field can accept almost anything.| +|`digest`|query|Digest of uploaded blob.| + + + + +###### On Success: Upload Complete + +``` +204 No Content +Location: +Content-Range: - +Content-Length: +``` + +The upload has been completed and accepted by the registry. The canonical location will be available in the `Location` header. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Location`|| +|`Content-Range`|Range of bytes identifying the desired block of content represented by the body. Start must match the end of offset retrieved via status check. Note that this is a non-standard use of the `Content-Range` header.| +|`Content-Length`|Length of the chunk being uploaded, corresponding the length of the request body.| + + + + +###### On Failure: Bad Request + +``` +400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +There was an error processing the upload and it must be restarted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to push to the repository. The following headers will be returned on the response: |Name|Description| |----|-----------| -|`Content-Range`|Range of bytes identifying the desired block of content represented by the body. Start must match the end of offset retrieved via status check. Note that this is a non-standard use of the `Content-Range` header.| -|`Content-Length`|Length of the chunk being uploaded, corresponding the length of the request body.| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Not Found + +``` +404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The upload is unknown to the registry. The upload must be restarted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + + + +###### On Failure: Requested Range Not Satisfiable + +``` +416 Requested Range Not Satisfiable +Location: /v2//blobs/uploads/ +Range: 0- +``` + +The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid. The contents of the `Range` header may be used to resolve the condition. + +The following headers will be returned on the response: + +|Name|Description| +|----|-----------| +|`Location`|The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.| +|`Range`|Range indicating the current progress of the upload.| @@ -1645,10 +2471,12 @@ The following headers will be returned on the response: Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. -##### ``` DELETE /v2//blobs/uploads/ +Host: +Authorization: +Content-Length: 0 ``` Cancel the upload specified by `uuid`. @@ -1658,12 +2486,133 @@ The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| +|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| +|`Authorization`|header|An RFC7235 compliant authorization header.| +|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.| |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept almost anything.| +###### On Success: Upload Deleted + +``` +204 No Content +Content-Length: 0 +``` + +The upload has been successfully deleted. + +The following headers will be returned with the response: + +|Name|Description| +|----|-----------| +|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| + + + + +###### On Failure: Bad Request + +``` +400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +An error was encountered processing the delete. The client may ignore this error. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | +| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | + + + +###### On Failure: Unauthorized + +``` +401 Unauthorized +WWW-Authenticate: realm="", ..." +Content-Length: +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": "UNAUTHORIZED", + "message": "access to the requested resource is not authorized", + "detail": ... + }, + ... + ] +} +``` + +The client does not have access to the repository. + +The following headers will be returned on the response: + +|Name|Description| +|----|-----------| +|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| +|`Content-Length`|Length of the JSON error response body.| + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. | + + + +###### On Failure: Not Found + +``` +404 Not Found +Content-Type: application/json; charset=utf-8 + +{ + "errors:" [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The upload is unknown to the registry. The client may ignore this error and assume the upload has been deleted. + + + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +-------|----|------|------------ +| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + + From 9c144046303733476d128d60f1905e01e7121c0b Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Fri, 2 Jan 2015 11:39:13 -0800 Subject: [PATCH 6/6] Address minor typos in response descriptions Signed-off-by: Stephen J Day --- api/v2/descriptors.go | 4 ++-- doc/SPEC.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/v2/descriptors.go b/api/v2/descriptors.go index 22ef32a03..a0569840c 100644 --- a/api/v2/descriptors.go +++ b/api/v2/descriptors.go @@ -550,7 +550,7 @@ var routeDescriptors = []RouteDescriptor{ Failures: []ResponseDescriptor{ { Name: "Invalid Manifest", - Description: "The recieved manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.", + Description: "The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.", StatusCode: http.StatusBadRequest, Body: BodyDescriptor{ ContentType: "application/json; charset=utf-8", @@ -890,7 +890,7 @@ var routeDescriptors = []RouteDescriptor{ }, Successes: []ResponseDescriptor{ { - Description: "The blob has been created in the registry and is available the provided location.", + Description: "The blob has been created in the registry and is available at the provided location.", StatusCode: http.StatusCreated, Headers: []ParameterDescriptor{ { diff --git a/doc/SPEC.md b/doc/SPEC.md index f79989f4f..b82d9d6b5 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -1151,7 +1151,7 @@ Content-Type: application/json; charset=utf-8 } ``` -The recieved manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request. +The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request. @@ -1789,7 +1789,7 @@ Location: Content-Length: 0 ``` -The blob has been created in the registry and is available the provided location. +The blob has been created in the registry and is available at the provided location. The following headers will be returned with the response: