From 2848dfe636ecf302e64ed1d602671a2c8c93271a Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Tue, 16 Jun 2020 11:48:14 -0500 Subject: [PATCH 01/21] Describe the pull workflow Signed-off-by: Peter Engelbert --- spec.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index de5c25a3..d5f0b595 100644 --- a/spec.md +++ b/spec.md @@ -86,7 +86,29 @@ Registry providers can self-cetify by submitting conformance results to [opencon #### Pull -TODO: describe the Pull category and the high-level details +##### Pulling Blobs + +To pull a blob, perform a `GET` request to a url in the following form: +`/v2//blobs/` + +`` is the namespace of the repository, and `` being the blob's digest. + +A GET request to an existing blob URL MUST provide the expected blob, with a reponse code that MUST be `200 OK`. + +If the blob is not found in the registry, the response code MUST be `404 Not Found`. + +##### Pulling manifests + +To pull a manifest, perform a `GET` request to a url in the following form: +`/v2//manifests/` + +`` refers to the namespace of the repository. `` MUST be either (a) the digest of the manifest or (b) a tag name. + +The `` MUST NOT be in any other format. + +A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`. + +If the manifest is not found in the registry, the response code MUST be `404 Not Found`. #### Push From 5404ebab23d7fd7e80fcba1f4ee710f11fe9d272 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Wed, 10 Jun 2020 13:59:58 -0500 Subject: [PATCH 02/21] mini update 2: new table of contents This is a new table of contents for the spec, designed to add simplicity and organization. Existing content will later be moved into one of these sections, or removed entirely if considered superfluous. Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 58 ++++++++++++++++----------------------------------------- 1 file changed, 16 insertions(+), 42 deletions(-) diff --git a/spec.md b/spec.md index 6ce6b735..8c48da78 100644 --- a/spec.md +++ b/spec.md @@ -13,49 +13,23 @@ The goal of this specification is to standardize container image distribution ba ### Table of Contents -- [Introduction](spec.md) -- [Notational Conventions](#notational-conventions) -- [Historical Context](#historical-context) -- [Scope](#scope) - - [Future](#future) -- [Use Cases](#use-cases) - - [Image Verification](#image-verification) - - [Resumable Push](#resumable-push) - - [Resumable Pull](#resumable-pull) - - [Layer Upload De-duplication](#layer-upload-de-duplication) -- [Changes](#changes) - [Overview](#overview) - - [Errors](#errors) - - [API Version Check](#api-version-check) - - [Content Digests](#content-digests) - - [Pulling An Image](#pulling-an-image) - - [Pushing An Image](#pushing-an-image) - - [Listing Repositories](#listing-repositories) - - [Listing Image Tags](#listing-image-tags) - - [Deleting an Image](#deleting-an-image) -- [Detail](#detail) - - [Errors](#errors-2) - - [Base](#base) - - [Tags](#tags) - - [Manifest](#manifest) - - [GET Manifest](#get-manifest) - - [PUT Manifest](#put-manifest) - - [DELETE Manifest](#delete-manifest) - - [Blob](#blob) - - [GET Blob](#get-blob) - - [Fetch Blob](#fetch-blob) - - [Fetch Blob Part](#fetch-blob-part) - - [DELETE Blob](#delete-blob) - - [Initiate Blob Upload](#initiate-blob-upload) - - [POST Initiate Blob Upload](#post-initiate-blob-upload) - - [Initiate Monolithic Blob Upload](#initiate-monolithic-blob-upload) - - [Initiate Resumable Blob Upload](#initiate-resumable-blob-upload) - - [Mount Blob](#mount-blob) - - [Blob Upload](#blob-upload) - - [GET Blob Upload](#get-blob-upload) - - [PATCH Blob Upload](#patch-blob-upload) - - [PUT Blob Upload](#put-blob-upload) - - [DELETE Blob Upload](#delete-blob-upload) + - [Introduction](#introduction) + - [Historical Context](#historical-context) +- [Definitions](#defintions) + - [Common Terms](#introduction) + - [Document Language](#document-language) +- [Conformance](#conformance) + - [Minimum Requirements](#minimum-requirements) + - [Official Certification](#official-certification) + - [Workflow Categories](#workflow-categories) + 1. [Pull](#pull) + 2. [Push](#push) + 3. [Content Discovery](#content-discovery) + 4. [Content Management](#content-management) +- [HTTP API](#http-api) + - [Endpoints](#endpoints) + - [Error Codes](#error-codes) ## Notational Conventions From 5f59ff77d89db998a6e128ee5f2e9926acde6ce9 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Fri, 26 Jun 2020 17:01:51 -0500 Subject: [PATCH 03/21] remove top-level defintions section Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index 8c48da78..6e6dfdaa 100644 --- a/spec.md +++ b/spec.md @@ -16,10 +16,9 @@ The goal of this specification is to standardize container image distribution ba - [Overview](#overview) - [Introduction](#introduction) - [Historical Context](#historical-context) -- [Definitions](#defintions) - - [Common Terms](#introduction) - - [Document Language](#document-language) + - [Definitions](#defintions) - [Conformance](#conformance) + - [Notational Conventions](#notational-conventions) - [Minimum Requirements](#minimum-requirements) - [Official Certification](#official-certification) - [Workflow Categories](#workflow-categories) From 2ded6d5b1835dd5fe69148a95da8a078811d1f39 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Wed, 10 Jun 2020 14:09:45 -0500 Subject: [PATCH 04/21] mini update 3: fill in overview section Fill in the overview section, including new introduction referring to "content" (vs. just container images). Move historical context section underneath overview. Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/spec.md b/spec.md index 6e6dfdaa..6648a535 100644 --- a/spec.md +++ b/spec.md @@ -5,13 +5,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, api, advanc --- # Open Container Initiative -## Distribution Specification - -This specification defines an API protocol to facilitate distribution of images. - -The goal of this specification is to standardize container image distribution based on the specification for the [Docker Registry HTTP API V2 protocol](https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md). - -### Table of Contents +## Table of Contents - [Overview](#overview) - [Introduction](#introduction) @@ -30,16 +24,15 @@ The goal of this specification is to standardize container image distribution ba - [Endpoints](#endpoints) - [Error Codes](#error-codes) -## Notational Conventions +## Overview -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). +### Introduction -The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. +The Open Container Initiative Distribution Specification defines an API protocol to facilitate and standardize the distribution of content, especially related to container images and associated artifacts. -An implementation is not compliant if it fails to satisfy one or more of the MUST, MUST NOT, REQUIRED, SHALL, or SHALL NOT requirements for the protocols it implements. -An implementation is compliant if it satisfies all the MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements for the protocols it implements. +### Historical Context -## Historical Context +The spec is based on the specification for the [Docker Registry HTTP API V2 protocol](https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md). For relevant details and a history leading up to this specification, please see the following issues: @@ -47,7 +40,14 @@ For relevant details and a history leading up to this specification, please see - [moby/moby#9015](https://github.com/moby/moby/issues/9015) - [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612) - +## Notational Conventions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). + +The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. + +An implementation is not compliant if it fails to satisfy one or more of the MUST, MUST NOT, REQUIRED, SHALL, or SHALL NOT requirements for the protocols it implements. +An implementation is compliant if it satisfies all the MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements for the protocols it implements. ## Scope From 2acd0fb5ee5d806cfb523abe1b8b7a6deda4d983 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Wed, 10 Jun 2020 14:20:51 -0500 Subject: [PATCH 05/21] mini update 4: fill in definitions section Fill in the definitions section, introducing several terms and defintions which will serve as reference for the rest of the document. Also moved the "notational conventions" section into this section, removing any language that seemed unnecessary or related to compliance (which will be covered in the conformance section). Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 6648a535..65605244 100644 --- a/spec.md +++ b/spec.md @@ -40,14 +40,27 @@ For relevant details and a history leading up to this specification, please see - [moby/moby#9015](https://github.com/moby/moby/issues/9015) - [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612) -## Notational Conventions +## Definitions -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). +### Common Terms + +Several terms are used frequently in this document and warrant basic definitions: -The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. +- **Registry**: a HTTP service which implements this spec +- **Client**: a tool that communicates with registries over HTTP +- **Push**: the act of uploading content to a registry +- **Pull**: the act of downloading content from a registry +- **Artifact**: a single piece of content, made up of a manifest and one or more layers +- **Manifest**: a JSON document which defines an artifact +- **Layer**: a single part of all the parts which comprise an artifact +- **Config**: a special layer defined at the top of a manifest containing artifact metadata +- **Blob**: a single binary content stored in a registry +- **Digest**: a unique blob identifier +- **Content**: a general term for content that can be downloaded from a registry (manifest or blob) -An implementation is not compliant if it fails to satisfy one or more of the MUST, MUST NOT, REQUIRED, SHALL, or SHALL NOT requirements for the protocols it implements. -An implementation is compliant if it satisfies all the MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements for the protocols it implements. +### Document Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). ## Scope From 922acfdad6413dd46a31413db9f3c924956e4932 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Fri, 26 Jun 2020 18:28:08 -0500 Subject: [PATCH 06/21] update digest and content definitions Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/spec.md b/spec.md index 65605244..44390b01 100644 --- a/spec.md +++ b/spec.md @@ -40,9 +40,7 @@ For relevant details and a history leading up to this specification, please see - [moby/moby#9015](https://github.com/moby/moby/issues/9015) - [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612) -## Definitions - -### Common Terms +### Definitions Several terms are used frequently in this document and warrant basic definitions: @@ -55,12 +53,8 @@ Several terms are used frequently in this document and warrant basic definitions - **Layer**: a single part of all the parts which comprise an artifact - **Config**: a special layer defined at the top of a manifest containing artifact metadata - **Blob**: a single binary content stored in a registry -- **Digest**: a unique blob identifier -- **Content**: a general term for content that can be downloaded from a registry (manifest or blob) - -### Document Language - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). +- **Digest**: a unique blob identifier, calculated from the blob's content +- **Content**: a general term for content that can be downloaded from a registry (manifest or blob), and are addressable by a digest ## Scope From 0b74a41ef3cc26204682e6b047007d6652038479 Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Wed, 10 Jun 2020 14:33:59 -0500 Subject: [PATCH 07/21] mini update 5: fill in conformance section (sans workflows) Fill in conformance section, adding minimum requirements stating that all compliant registries must at least support Pull. Added a section regarding certification, linking to the opencontainers/oci-conformance repo. For the workflow sections, intentionally left blank, and will be added in a follow-up PR. Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/spec.md b/spec.md index 44390b01..ee160020 100644 --- a/spec.md +++ b/spec.md @@ -56,6 +56,43 @@ Several terms are used frequently in this document and warrant basic definitions - **Digest**: a unique blob identifier, calculated from the blob's content - **Content**: a general term for content that can be downloaded from a registry (manifest or blob), and are addressable by a digest +## Conformance + +### Minimum Requirements + +For a registry to be considered fully conformant against this specification, it must implement the HTTP endpoints required by each of the four (4) major workflow categories: + +1. **Pull** (REQUIRED) - Ability to fetch content from a registry +2. **Push** - Ability to publish content to a registry +3. **Content Discovery** - Ability to list or otherwise query the content stored in a registry +4. **Content Management** - Ability to delete (or otherwise manipulate) content stored in a registry + +At a bare minimum, registries claiming to be "OCI-Compliant" MUST support all facets of the pull workflow. + +In order to test a registry's conformance against these workflows, please use the [conformance testing tool](./conformance/). + +### Official Certification + +Registry providers can self-cetify by submitting conformance results to [opencontainers/oci-conformance](https://github.com/opencontainers/oci-conformance). + +### Workflow Categories + +#### Pull + +TODO: describe the Pull category and the high-level details + +#### Push + +TODO: describe the Push category and the high-level details + +#### Content Discovery + +TODO: describe the Content Discovery category and the high-level details + +#### Content Management + +TODO: describe the Content Management category and the high-level details + ## Scope This specification covers URL layout and protocols for interaction between a registry and registry client. From 43fa8789e27c26ab72b8a9f19a4cbf53a93b4b4c Mon Sep 17 00:00:00 2001 From: jdolitsky <393494+jdolitsky@users.noreply.github.com> Date: Wed, 10 Jun 2020 14:33:59 -0500 Subject: [PATCH 08/21] mini update 5: fill in conformance section (sans workflows) Fill in conformance section, adding minimum requirements stating that all compliant registries must at least support Pull. Added a section regarding certification, linking to the opencontainers/oci-conformance repo. For the workflow sections, intentionally left blank, and will be added in a follow-up PR. Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com> --- spec.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/spec.md b/spec.md index ee160020..6e9551de 100644 --- a/spec.md +++ b/spec.md @@ -93,6 +93,43 @@ TODO: describe the Content Discovery category and the high-level details TODO: describe the Content Management category and the high-level details +## Conformance + +### Minimum Requirements + +For a registry to be considered fully conformant against this specification, it must implement the HTTP endpoints required by each of the four (4) major workflow categories: + +1. **Pull** (REQUIRED) - Ability to fetch content from a registry +2. **Push** - Ability to publish content to a registry +3. **Content Discovery** - Ability to list or otherwise query the content stored in a registry +4. **Content Management** - Ability to delete (or otherwise manipulate) content stored in a registry + +At a bare minimum, registries claiming to be "OCI-Compliant" MUST support all facets of the pull workflow. + +In order to test a registry's conformance against these workflows, please use the [conformance testing tool](./conformance/). + +### Official Certification + +Registry providers can self-cetify by submitting conformance results to [opencontainers/oci-conformance](https://github.com/opencontainers/oci-conformance). + +### Workflow Categories + +#### Pull + +TODO: describe the Pull category and the high-level details + +#### Push + +TODO: describe the Push category and the high-level details + +#### Content Discovery + +TODO: describe the Content Discovery category and the high-level details + +#### Content Management + +TODO: describe the Content Management category and the high-level details + ## Scope This specification covers URL layout and protocols for interaction between a registry and registry client. From a367759ef20e87d4fb4da990e7e45085dc242dfe Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Tue, 16 Jun 2020 11:48:14 -0500 Subject: [PATCH 09/21] Describe the pull workflow Signed-off-by: Peter Engelbert --- spec.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 6e9551de..c0d9e9f9 100644 --- a/spec.md +++ b/spec.md @@ -116,7 +116,29 @@ Registry providers can self-cetify by submitting conformance results to [opencon #### Pull -TODO: describe the Pull category and the high-level details +##### Pulling Blobs + +To pull a blob, perform a `GET` request to a url in the following form: +`/v2//blobs/` + +`` is the namespace of the repository, and `` being the blob's digest. + +A GET request to an existing blob URL MUST provide the expected blob, with a reponse code that MUST be `200 OK`. + +If the blob is not found in the registry, the response code MUST be `404 Not Found`. + +##### Pulling manifests + +To pull a manifest, perform a `GET` request to a url in the following form: +`/v2//manifests/` + +`` refers to the namespace of the repository. `` MUST be either (a) the digest of the manifest or (b) a tag name. + +The `` MUST NOT be in any other format. + +A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`. + +If the manifest is not found in the registry, the response code MUST be `404 Not Found`. #### Push From 801afc1c23e0ad74a46bdb95fb18314a88592fbe Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 10:07:56 -0500 Subject: [PATCH 10/21] Adjust grammar Signed-off-by: Peter Engelbert --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 9b449685..9571aec1 100644 --- a/spec.md +++ b/spec.md @@ -84,7 +84,7 @@ Registry providers can self-certify by submitting conformance results to [openco To pull a blob, perform a `GET` request to a url in the following form: `/v2//blobs/` -`` is the namespace of the repository, and `` being the blob's digest. +`` is the namespace of the repository, and `` is the blob's digest. A GET request to an existing blob URL MUST provide the expected blob, with a reponse code that MUST be `200 OK`. From 4933b3157b09e723e645baa3ebe64dd4be86106f Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Tue, 16 Jun 2020 12:08:47 -0500 Subject: [PATCH 11/21] Describe push workflow Signed-off-by: Peter Engelbert --- spec.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 180 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 9571aec1..47aa3786 100644 --- a/spec.md +++ b/spec.md @@ -105,7 +105,186 @@ If the manifest is not found in the registry, the response code MUST be `404 Not #### Push -TODO: describe the Push category and the high-level details +##### Pushing blobs + +There are two ways to push blobs: chunked or monolithic. + +##### Pushing a blob monolithically + +There are two ways to push a blob monolithically: +1. A single`POST` request +2. A `POST` request followed by a `PUT` request + +--- + +To push a blob monolithically by the *first method*, perform a `POST` request to a URL in the following form, and with the following headers and body: + +`/v2//blobs/uploads/?digest=` +``` +Content-Length: +Content-Type: application/octet-stream +``` +``` + +``` + +With `` being the repository's namespace, `` being the blob's digest, and `` being the size (in bytes) of the blob. + +The `Content-Length` header MUST match the blob's actual content length. Likewise, the `` MUST match the blob's digest. + +Successful completion of the request MUST return a `201 Created` code, and MUST include the following header: + +``` +Location: +``` + +With `` being a pullable blob URL. + +--- + +To push a blob monolithically by the *second method*, there are two steps: +1. Obtain a session id (upload URL) +2. Upload the blob to said URL + +To obtain a session ID, perform a `POST` request to a URL in the following format: + +`/v2//blobs/uploads/` + +Here, `` refers to the namespace of the repository. Upon success, the response MUST have a code of `202 Accepted`, and MUST include the following header: + +``` +Location: +``` + +The `` MUST contain a UUID representing a unique session ID for the upload to follow. + +Optionally, the location MAY be absolute (containing the protocol and/or hostname), or it MAY be relative (containing just the URL path). + +Once the `` has been obtained, perform the upload proper by making a `PUT` request to the following URL path, and with the following headers and body: + +`?digest=` +``` +Content-Length: +Content-Type: aplication/octet-stream +``` +``` + +``` + +The `` MAY contain critical query parameters. Additionally, it SHOULD match exactly the `` obtained from the `POST` request. It SHOULD NOT be assembled manually by clients except where absolute/relative conversion is necessary. + +Here, `` is the digest of the blob being uploaded, and `` is its size in bytes. + +Upon successful completion of the request, the response MUST have code `201 Created` and MUST have the following header: + +``` +Location: +``` + +With `` being a pullable blob URL. + +##### Pushing a blob in chunks + +A chunked blob upload is accomplished in three phases: +1. Obtain a session ID (upload URL) (`POST`) +2. Upload the chunks (`PATCH`) +3. Close the session (`PUT`) + +For information on obtaining a session ID, reference the above section on pushing a blob monolithically via the `POST`/`PUT` method. The process remains unchanged for chunked upload, except that the post request MUST include the following header: + +``` +Content-Length: 0 +``` + +Please reference the above section for restrictions on the ``. + +--- +To upload a chunk, issue a `PATCH` request to a URL path in the following format, and with the following headers and body: + +URL path: `` +``` +Content-Type: application/octet-stream +Content-Range: +Content-Length: +``` +``` + +``` + +The `` refers to the URL obtained from the preceding `POST` request. + +The `` refers to the byte range of the chunk, and MUST be inclusive on both ends. The first chunk's range MUST begin with `0`. It MUST match the following regular expression: + +```regexp +^[0-9]+-[0-9]+$ +``` + +The `` is the content-length, in bytes, of the current chunk. + +Each successful chunk upload MUST have a `202 Accepted` response code, and MUST have the following header: + +``` +Location +``` + +Each consecutive chunk upload SHOULD use the `` provided in the response to the previous chunk upload. + +Chunks MUST be uploaded in order, with the first byte of a chunk being the last chunk's `` plus one. If a chunk is uploaded out of order, the registry MUST respond with a `416 Requested Range Not Satisfiable` code. + +The final chunk MAY be uploaded using a `PATCH` request or it MAY be uploaded in the closing `PUT` request. Regardless of how the final chunk is uploaded, the session MUST be closed with a `PUT` request. + +--- + +To close the session, issue a `PUT` request to a url in the following format, and with the following headers (and optional body, depending on whether or not the final chunk was uploaded already via a `PATCH` request): + +`?digest=` +``` +Content-Length: +Content-Range: +Content-Type: application/octet-stream +``` +``` +OPTIONAL: +``` + +The closing `PUT` request MUST include the `` of the whole blob (not the final chunk) as a query parameter. + +The response to a successful closing of the session MUST be `201 Created`, and MUST contain the following header: +``` +Location: +``` + +Here, `` is a pullable blob URL. + + +##### Pushing Manifests + +To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers +and body: +`/v2//manifests/` +```http request +Content-Type: application/vnd.oci.image.manifest.v1+json +``` +``` + +``` + +`` is the namespace of the repository, and the `` MUST be either a) a digest or b) a tag. +```regexp +^[0-9]+-[0-9]+$ +``` + +The uploaded manifest MUST reference any layers that make up the repository. However, the layers field MAY +be empty. Upon a successful upload, the registry MUST return response code `201 Created`, and MUST have the +following header: + +```http request +Location: +``` + +The `` is a pullable manifest URL. + +An attempt to pull a nonexistent repository MUST return response code `404 Not Found` #### Content Discovery From d44db2dcb7a00f07c266e929dafa641987691c75 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 10:17:27 -0500 Subject: [PATCH 12/21] Fix typos and English errors Signed-off-by: Peter Engelbert --- spec.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/spec.md b/spec.md index 47aa3786..92d96e77 100644 --- a/spec.md +++ b/spec.md @@ -112,12 +112,12 @@ There are two ways to push blobs: chunked or monolithic. ##### Pushing a blob monolithically There are two ways to push a blob monolithically: -1. A single`POST` request +1. A single `POST` request 2. A `POST` request followed by a `PUT` request --- -To push a blob monolithically by the *first method*, perform a `POST` request to a URL in the following form, and with the following headers and body: +To push a blob monolithically by using a single POST request, perform a `POST` request to a URL in the following form, and with the following headers and body: `/v2//blobs/uploads/?digest=` ``` @@ -128,11 +128,11 @@ Content-Type: application/octet-stream ``` -With `` being the repository's namespace, `` being the blob's digest, and `` being the size (in bytes) of the blob. +Here, `` is the repository's namespace, `` is the blob's digest, and `` is the size (in bytes) of the blob. The `Content-Length` header MUST match the blob's actual content length. Likewise, the `` MUST match the blob's digest. -Successful completion of the request MUST return a `201 Created` code, and MUST include the following header: +Successful completion of the request MUST return a `201 Created`, and MUST include the following header: ``` Location: @@ -142,7 +142,7 @@ With `` being a pullable blob URL. --- -To push a blob monolithically by the *second method*, there are two steps: +To push a blob monolithically by using a POST request followed by a PUT request, there are two steps: 1. Obtain a session id (upload URL) 2. Upload the blob to said URL @@ -262,7 +262,7 @@ Here, `` is a pullable blob URL. To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers and body: `/v2//manifests/` -```http request +``` Content-Type: application/vnd.oci.image.manifest.v1+json ``` ``` @@ -270,15 +270,12 @@ Content-Type: application/vnd.oci.image.manifest.v1+json ``` `` is the namespace of the repository, and the `` MUST be either a) a digest or b) a tag. -```regexp -^[0-9]+-[0-9]+$ -``` -The uploaded manifest MUST reference any layers that make up the repository. However, the layers field MAY +The uploaded manifest MUST reference any layers that make up the artifact. However, the layers field MAY be empty. Upon a successful upload, the registry MUST return response code `201 Created`, and MUST have the following header: -```http request +``` Location: ``` From b5adeb661190e4671e5f3cdb503f1e73cdc435ea Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Mon, 29 Jun 2020 11:23:33 -0500 Subject: [PATCH 13/21] Add content discovery section to spec Signed-off-by: Peter Engelbert --- spec.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 92d96e77..76521ce5 100644 --- a/spec.md +++ b/spec.md @@ -285,7 +285,47 @@ An attempt to pull a nonexistent repository MUST return response code `404 Not F #### Content Discovery -TODO: describe the Content Discovery category and the high-level details +Content Discovery provides a way of discovering which tags are available for a given repository. + +To fetch the list of tags, perform a `GET` request to a path in the following format: +`/v2//tags/list` + +`` is the namespace of the repository. Assuming a repository is found, Content Discovery endpoints MUST return a +`200 OK` response code. The list of tags MAY be empty, if there are no tags on the repository. If the list is not empty, +the tags MUST be in lexical order (i.e. case-insensitive alphanumeric order). + +Upon success, the response MUST be a json body in the following format: +```json +{ + "name": "", + "tags": [ + "", + "", + "" + ] +} +``` + +`` is the namespace of the repository, and ``, ``, and `` are each tags on the repository. + +In addition to fetching the whole list of tags, a subset of the tags can be fetched by providing the `n` query parameter. +In this case, the path will look like the following: +`/v2//tags/list?n=` + +`` is the namespace of the repository, and `` is an integer specifying the number of tags requested. The response +to such a request MAY return fewer than `` results, but ONLY when the total number of tags attached to the repository +is less than ``. Otherwise, the response MUST include `` results. Without the `last` query parameter (described +next), the list returned will start at the beginning of the list and include `` results. As above, the tags MUST be +in lexical order. + +The `last` query parameter provides further means for limiting the number of tags. It is used exclusively in combination with the +`n` parameter: +`/v2//tags/list?n=&last=` + +`` is the namespace of the repository, `` is the number of tags requested, and `` is the *value* of +the last tag. `` MUST NOT be an index, but rather it MUST be a proper tag. A request of this sort will return +up to `` tags, beginning non-inclusively with ``. That is to say, `` will not be included in the +results, but up to `` tags *after* `` will be returned. The tags MUST be in lexical order. #### Content Management From 4797796905f8a3704d7e10debfeac46b68746f62 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 10:27:44 -0500 Subject: [PATCH 14/21] Make small language improvements Signed-off-by: Peter Engelbert --- spec.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 76521ce5..c2f48261 100644 --- a/spec.md +++ b/spec.md @@ -285,12 +285,12 @@ An attempt to pull a nonexistent repository MUST return response code `404 Not F #### Content Discovery -Content Discovery provides a way of discovering which tags are available for a given repository. +Currently, the only functionality provided by this workflow is the ability to discover tags. To fetch the list of tags, perform a `GET` request to a path in the following format: `/v2//tags/list` -`` is the namespace of the repository. Assuming a repository is found, Content Discovery endpoints MUST return a +`` is the namespace of the repository. Assuming a repository is found, this request MUST return a `200 OK` response code. The list of tags MAY be empty, if there are no tags on the repository. If the list is not empty, the tags MUST be in lexical order (i.e. case-insensitive alphanumeric order). @@ -313,17 +313,19 @@ In this case, the path will look like the following: `/v2//tags/list?n=` `` is the namespace of the repository, and `` is an integer specifying the number of tags requested. The response -to such a request MAY return fewer than `` results, but ONLY when the total number of tags attached to the repository +to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository is less than ``. Otherwise, the response MUST include `` results. Without the `last` query parameter (described next), the list returned will start at the beginning of the list and include `` results. As above, the tags MUST be in lexical order. The `last` query parameter provides further means for limiting the number of tags. It is used exclusively in combination with the `n` parameter: -`/v2//tags/list?n=&last=` +``` +/v2//tags/list?n=&last= +``` `` is the namespace of the repository, `` is the number of tags requested, and `` is the *value* of -the last tag. `` MUST NOT be an index, but rather it MUST be a proper tag. A request of this sort will return +the last tag. `` MUST NOT be a numerical index, but rather it MUST be a proper tag. A request of this sort will return up to `` tags, beginning non-inclusively with ``. That is to say, `` will not be included in the results, but up to `` tags *after* `` will be returned. The tags MUST be in lexical order. From 1e90b5524c41c6fbed2b11d02611fef3179e9cd2 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Mon, 29 Jun 2020 13:43:50 -0500 Subject: [PATCH 15/21] Describe content management workflow Signed-off-by: Peter Engelbert --- spec.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index c2f48261..4a381bab 100644 --- a/spec.md +++ b/spec.md @@ -331,7 +331,30 @@ results, but up to `` tags *after* `` will be returned. The tags M #### Content Management -TODO: describe the Content Management category and the high-level details +##### Deleting tags +Content management refers to the deletion of blobs, tags and manifests. Registries MAY implement deletion or they MAY dis- +able it. Similarly, a registry MAY implement tag deletion, while others MAY allow deletion only by manifest. + +`` is the namespace of the repository, and `` is the name of the tag to be deleted. Upon success, the registry +MUST respond with a `202 Accepted` code. If tag deletion is disabled, the registry MUST respond with a `400 Bad Request` +code. + +To delete a tag, perform a `DELETE` request to a path in the following format: +`/v2//manifests/` + +##### Deleting Manifests +To delete a manifest, perform a `DELETE` request to a path in the following format: +`/v2//manifests/` + +`` is the namespace of the repository, and `` is the digest of the manifest to be deleted. Upon success, the registry +MUST respond with a `202 Accepted` code. If the repository does not exist, the response MUST bear the code `404 Not Found`. + +##### Deleting Blobs +To delete a blob, perform a `DELETE` request to a path in the following format: +`/v2//blobs/` + +`` is the namespace of the repository, and `` is the digest of the blob to be deleted. Upon success, the +registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 Not Found` code MUST be returned. ## Scope From c03bb796cb28fc1303cbb03851c7cb885d5f4b96 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 10:33:14 -0500 Subject: [PATCH 16/21] Make small language fixes Signed-off-by: Peter Engelbert --- spec.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 4a381bab..e4f31279 100644 --- a/spec.md +++ b/spec.md @@ -330,14 +330,13 @@ up to `` tags, beginning non-inclusively with ``. That is to say, results, but up to `` tags *after* `` will be returned. The tags MUST be in lexical order. #### Content Management +Content management refers to the deletion of blobs, tags, and manifests. Registries MAY implement deletion or they MAY +disable it. Similarly, a registry MAY implement tag deletion, while others MAY allow deletion only by manifest. ##### Deleting tags -Content management refers to the deletion of blobs, tags and manifests. Registries MAY implement deletion or they MAY dis- -able it. Similarly, a registry MAY implement tag deletion, while others MAY allow deletion only by manifest. - `` is the namespace of the repository, and `` is the name of the tag to be deleted. Upon success, the registry -MUST respond with a `202 Accepted` code. If tag deletion is disabled, the registry MUST respond with a `400 Bad Request` -code. +MUST respond with a `202 Accepted` code. If tag deletion is disabled, the registry MUST respond with either a +`400 Bad Request` or a `405 Method Not Allowed`. To delete a tag, perform a `DELETE` request to a path in the following format: `/v2//manifests/` @@ -347,7 +346,7 @@ To delete a manifest, perform a `DELETE` request to a path in the following form `/v2//manifests/` `` is the namespace of the repository, and `` is the digest of the manifest to be deleted. Upon success, the registry -MUST respond with a `202 Accepted` code. If the repository does not exist, the response MUST bear the code `404 Not Found`. +MUST respond with a `202 Accepted` code. If the repository does not exist, the response MUST return `404 Not Found`. ##### Deleting Blobs To delete a blob, perform a `DELETE` request to a path in the following format: From a2b8c8489f5444bf3194882feef91ed3124e7d60 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 22 Jul 2020 11:04:10 -0500 Subject: [PATCH 17/21] Add endpoint table to spec Signed-off-by: Peter Engelbert --- spec.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/spec.md b/spec.md index e4f31279..d92c5d23 100644 --- a/spec.md +++ b/spec.md @@ -355,6 +355,24 @@ To delete a blob, perform a `DELETE` request to a path in the following format: `` is the namespace of the repository, and `` is the digest of the blob to be deleted. Upon success, the registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 Not Found` code MUST be returned. +### API + +#### Endpoints +| ID | API endpoint | Accepted Successful Response Codes | Accepted Failure Response Codes | +| ---|---|---|---| +| 1a | `GET /v2/` | `200` | `404`/`401` | +| 2a | `GET /v2//blobs/` | `200` | `404` | +| 3a | `GET /v2//manifests/` | `200` | `404` | +| 4a | `POST /v2//blobs/uploads/` | `202` | `404` | +| 4b | `POST /v2//blobs/uploads/?digest=` | `201` | `404`/`400` | +| 5a | `PATCH /v2//blobs/uploads/` | `202` | `404`/`416` | +| 6a | `PUT /v2//blobs/uploads/?digest=` | `201` | `404`/`400` | +| 7a | `PUT /v2//manifests/` | `201` | `404` | +| 8a | `GET /v2//tags/list` | `200` | `404` | +| 8b | `GET /v2//tags/list?n=&last=` | `200` | `404` | +| 9a | `DELETE /v2//manifests/` | `202` | `404`/`400`/`405` | +| 10a | `DELETE /v2//blobs/` | `202` | `404`/`405` | + ## Scope This specification covers URL layout and protocols for interaction between a registry and registry client. From 08f7078916e342524aad6d0a0ccaaac86d6df180 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 10:37:30 -0500 Subject: [PATCH 18/21] Add summary and place method into its own column Signed-off-by: Peter Engelbert --- spec.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/spec.md b/spec.md index d92c5d23..7906bbd3 100644 --- a/spec.md +++ b/spec.md @@ -356,22 +356,23 @@ To delete a blob, perform a `DELETE` request to a path in the following format: registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 Not Found` code MUST be returned. ### API +The API operates over HTTP. Below is a summary of the endpoints used by the API. #### Endpoints -| ID | API endpoint | Accepted Successful Response Codes | Accepted Failure Response Codes | -| ---|---|---|---| -| 1a | `GET /v2/` | `200` | `404`/`401` | -| 2a | `GET /v2//blobs/` | `200` | `404` | -| 3a | `GET /v2//manifests/` | `200` | `404` | -| 4a | `POST /v2//blobs/uploads/` | `202` | `404` | -| 4b | `POST /v2//blobs/uploads/?digest=` | `201` | `404`/`400` | -| 5a | `PATCH /v2//blobs/uploads/` | `202` | `404`/`416` | -| 6a | `PUT /v2//blobs/uploads/?digest=` | `201` | `404`/`400` | -| 7a | `PUT /v2//manifests/` | `201` | `404` | -| 8a | `GET /v2//tags/list` | `200` | `404` | -| 8b | `GET /v2//tags/list?n=&last=` | `200` | `404` | -| 9a | `DELETE /v2//manifests/` | `202` | `404`/`400`/`405` | -| 10a | `DELETE /v2//blobs/` | `202` | `404`/`405` | +| ID | Method | API endpoint | Accepted Successful Response Codes | Accepted Failure Response Codes | +| ---| --- | ---|---|---| +| 1a | `GET` | `/v2/` | `200` | `404`/`401` | +| 2a | `GET` | `/v2//blobs/` | `200` | `404` | +| 3a | `GET` | `/v2//manifests/` | `200` | `404` | +| 4a | `POST` | `/v2//blobs/uploads/` | `202` | `404` | +| 4b | `POST` | `/v2//blobs/uploads/?digest=` | `201` | `404`/`400` | +| 5a | `PATCH` | `/v2//blobs/uploads/` | `202` | `404`/`416` | +| 6a | `PUT` | `/v2//blobs/uploads/?digest=` | `201` | `404`/`400` | +| 7a | `PUT` | `/v2//manifests/` | `201` | `404` | +| 8a | `GET` | `/v2//tags/list` | `200` | `404` | +| 8b | `GET` | `/v2//tags/list?n=&last=` | `200` | `404` | +| 9a | `DELETE` | `/v2//manifests/` | `202` | `404`/`400`/`405` | +| 10a | `DELETE` | `/v2//blobs/` | `202` | `404`/`405` | ## Scope From ecf4822dc5f44a581063d2d64c2f84ca3c992099 Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 22 Jul 2020 14:05:49 -0500 Subject: [PATCH 19/21] Add 'error codes' section Signed-off-by: Peter Engelbert --- spec.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/spec.md b/spec.md index 7906bbd3..e820d4af 100644 --- a/spec.md +++ b/spec.md @@ -374,6 +374,48 @@ The API operates over HTTP. Below is a summary of the endpoints used by the API. | 9a | `DELETE` | `/v2//manifests/` | `202` | `404`/`400`/`405` | | 10a | `DELETE` | `/v2//blobs/` | `202` | `404`/`405` | +#### Error Codes + +A `4XX` response code from the registry MAY return a body in any format. If the response body is in JSON format, it MUST +have the following format: + +```json + { + "errors": [ + { + "code": "", + "message": "", + "detail": "" + }, + ... + ] + } +``` + +The `code` field MUST be a unique identifier, containing only uppercase alphabetic characters and underscores. The +`message` field is OPTIONAL, and if present, it SHOULD be a human readable string or MAY be empty. The `detail` field is +OPTIONAL and MAY contain arbitrary JSON data providing information the client can use to resolve the issue. + +The `code` field MUST be one of the following: + +| Code | Description | +|-------------------------|------------------------------------------------| +| `BLOB_UNKNOWN` | blob unknown to registry | +| `BLOB_UPLOAD_INVALID` | blob upload invalid | +| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | +| `DIGEST_INVALID` | provided digest did not match uploaded content | +| `MANIFEST_BLOB_UNKNOWN` | blob unknown to registry | +| `MANIFEST_INVALID` | manifest invalid | +| `MANIFEST_UNKNOWN` | manifest unknown | +| `MANIFEST_UNVERIFIED` | manifest failed signature verification | +| `NAME_INVALID` | invalid repository name | +| `NAME_UNKNOWN` | repository name not known to registry | +| `SIZE_INVALID` | provided length did not match content length | +| `TAG_INVALID` | manifest tag did not match URI | +| `UNAUTHORIZED` | authentication required | +| `DENIED` | requested access to the resource is denied | +| `UNSUPPORTED` | the operation is unsupported | + ## Scope This specification covers URL layout and protocols for interaction between a registry and registry client. From 35df22993d377f850e19ff41f82713663fd578dc Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 11:19:50 -0500 Subject: [PATCH 20/21] Add references and links to endpoint IDs Signed-off-by: Peter Engelbert --- spec.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/spec.md b/spec.md index e820d4af..5d41a2c3 100644 --- a/spec.md +++ b/spec.md @@ -82,7 +82,7 @@ Registry providers can self-certify by submitting conformance results to [openco ##### Pulling Blobs To pull a blob, perform a `GET` request to a url in the following form: -`/v2//blobs/` +[2a](#Endpoints) `/v2//blobs/` `` is the namespace of the repository, and `` is the blob's digest. @@ -93,7 +93,7 @@ If the blob is not found in the registry, the response code MUST be `404 Not Fou ##### Pulling manifests To pull a manifest, perform a `GET` request to a url in the following form: -`/v2//manifests/` +[3a](#Endpoints) `/v2//manifests/` `` refers to the namespace of the repository. `` MUST be either (a) the digest of the manifest or (b) a tag name. @@ -119,7 +119,7 @@ There are two ways to push a blob monolithically: To push a blob monolithically by using a single POST request, perform a `POST` request to a URL in the following form, and with the following headers and body: -`/v2//blobs/uploads/?digest=` +[4b](#Endpoints) `/v2//blobs/uploads/?digest=` ``` Content-Length: Content-Type: application/octet-stream @@ -148,7 +148,7 @@ To push a blob monolithically by using a POST request followed by a PUT request, To obtain a session ID, perform a `POST` request to a URL in the following format: -`/v2//blobs/uploads/` +[4a](#Endpoints) `/v2//blobs/uploads/` Here, `` refers to the namespace of the repository. Upon success, the response MUST have a code of `202 Accepted`, and MUST include the following header: @@ -162,7 +162,7 @@ Optionally, the location MAY be absolute (containing the protocol and/or hostnam Once the `` has been obtained, perform the upload proper by making a `PUT` request to the following URL path, and with the following headers and body: -`?digest=` +[6a](#Endpoints) `?digest=` ``` Content-Length: Content-Type: aplication/octet-stream @@ -201,7 +201,7 @@ Please reference the above section for restrictions on the ``. --- To upload a chunk, issue a `PATCH` request to a URL path in the following format, and with the following headers and body: -URL path: `` +URL path: [5a](#Endpoints) `` ``` Content-Type: application/octet-stream Content-Range: @@ -261,7 +261,7 @@ Here, `` is a pullable blob URL. To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers and body: -`/v2//manifests/` +[7a](#Endpoints) `/v2//manifests/` ``` Content-Type: application/vnd.oci.image.manifest.v1+json ``` @@ -288,7 +288,7 @@ An attempt to pull a nonexistent repository MUST return response code `404 Not F Currently, the only functionality provided by this workflow is the ability to discover tags. To fetch the list of tags, perform a `GET` request to a path in the following format: -`/v2//tags/list` +[8a](#Endpoints) `/v2//tags/list` `` is the namespace of the repository. Assuming a repository is found, this request MUST return a `200 OK` response code. The list of tags MAY be empty, if there are no tags on the repository. If the list is not empty, @@ -310,7 +310,7 @@ Upon success, the response MUST be a json body in the following format: In addition to fetching the whole list of tags, a subset of the tags can be fetched by providing the `n` query parameter. In this case, the path will look like the following: -`/v2//tags/list?n=` +[8b](#Endpoints) `/v2//tags/list?n=` `` is the namespace of the repository, and `` is an integer specifying the number of tags requested. The response to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository @@ -320,9 +320,7 @@ in lexical order. The `last` query parameter provides further means for limiting the number of tags. It is used exclusively in combination with the `n` parameter: -``` -/v2//tags/list?n=&last= -``` +[8b](#Endpoints) `/v2//tags/list?n=&last=` `` is the namespace of the repository, `` is the number of tags requested, and `` is the *value* of the last tag. `` MUST NOT be a numerical index, but rather it MUST be a proper tag. A request of this sort will return @@ -339,18 +337,18 @@ MUST respond with a `202 Accepted` code. If tag deletion is disabled, the regist `400 Bad Request` or a `405 Method Not Allowed`. To delete a tag, perform a `DELETE` request to a path in the following format: -`/v2//manifests/` +[9a](#Endpoints) `/v2//manifests/` ##### Deleting Manifests To delete a manifest, perform a `DELETE` request to a path in the following format: -`/v2//manifests/` +[9a](#Endpoints) `/v2//manifests/` `` is the namespace of the repository, and `` is the digest of the manifest to be deleted. Upon success, the registry MUST respond with a `202 Accepted` code. If the repository does not exist, the response MUST return `404 Not Found`. ##### Deleting Blobs To delete a blob, perform a `DELETE` request to a path in the following format: -`/v2//blobs/` +[10a](#Endpoints) `/v2//blobs/` `` is the namespace of the repository, and `` is the digest of the blob to be deleted. Upon success, the registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 Not Found` code MUST be returned. @@ -803,7 +801,7 @@ Range: bytes=0-0 To get the status of an upload, issue a GET request to the upload URL: ```HTTP -GET /v2//blobs/uploads/ +GET /v2//globs/uploads/ Host: ``` From a4ce0928fb854b3745c448319593800e41e8cecf Mon Sep 17 00:00:00 2001 From: Peter Engelbert Date: Wed, 29 Jul 2020 14:08:42 -0500 Subject: [PATCH 21/21] Update definitions Signed-off-by: Peter Engelbert --- spec.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 5d41a2c3..3848c999 100644 --- a/spec.md +++ b/spec.md @@ -49,10 +49,11 @@ Several terms are used frequently in this document and warrant basic definitions - **Push**: the act of uploading blobs and manifests to a registry - **Pull**: the act of downloading blobs and manifests from a registry - **Blob**: the binary form of content that is stored by a registry, addressable by a digest -- **Manifest**: a JSON document which defines an artifact +- **Manifest**: a JSON document which defines an artifact. Manifests are defined under the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/master/manifest.md) - **Config**: a section in the manifest (and associated blob) which contains artifact metadata - **Artifact**: one conceptual piece of content stored as blobs with an accompanying manifest containing a config -- **Digest**: a unique identifier created from a cryptographic hash of a blob's content +- **Digest**: a unique identifier created from a cryptographic hash of a blob's content. Digests are defined under the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/b6e51fa50549ee0bd5188494912a7f4c382cb0d4/descriptor.md#digests) +- **Tag**: a custom, human-readable manifest identifier ## Conformance @@ -356,6 +357,15 @@ registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 ### API The API operates over HTTP. Below is a summary of the endpoints used by the API. +#### Determining Support +To check whether or not the registry implements this specification, perform a `GET` request to the following endpoint: +[1a](#Endpoints) `/v2/`. + +If the response is `200 OK`, then the registry implements this specification. + +This endpoint MAY be used for authentication/authorization purposes, but this is out of the purview +of this specification. + #### Endpoints | ID | Method | API endpoint | Accepted Successful Response Codes | Accepted Failure Response Codes | | ---| --- | ---|---|---|