mini update 6: describe pull workflow (#166)

* Spec reorganization pt 1

Related to #126

The following sections have been removed:
- Changes
- Historical Context (already in reorg)
- Overview / Listing Repositories (unused catalog API)

The following sections have been moved into commented reorg:
- Notational Conventions ---> Definitions / Document Language
- Overview / Errors ---> HTTP API / Error Codes
- Overview / API Version Check ---> Conformance / Workflow Categories / Pull
- Overview / Pulling An Image ---> Conformance / Workflow Categories / Pull
- Overview / Pushing An Image ---> Conformance / Workflow Categories / Push
- Overview / Listing Image Tags ---> Conformance / Workflow Categories / Content Discovery
- Overview / Deleting an Image ---> Conformance / Workflow Categories / Content Management
- Detail / Errors ---> HTTP API / Error Codes

Signed-off-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>

* 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>

* 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>

* Describe the pull workflow

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

* update digest and content definitions

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add notational conventions section

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update description of content management

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* 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>

* remove top-level defintions section

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* 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>

* 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>

* update digest and content definitions

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* 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>

* 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>

* Describe the pull workflow

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

* update definitions based on github review

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add addressable by a digest

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* replace the with a

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* replace metadata with config

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add and associated blob

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update digest definition

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* a cryptographic hash vs. the

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update based on PR comments

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* capital MUST

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* merge conflicts

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* manual rebase on reorg

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* Adjust grammar

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Co-authored-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>

spec.md

@@ -79,7 +79,29 @@ Registry providers can self-certify by submitting conformance results to [openco
 
 #### 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/<name>/blobs/<digest>`
+
+`<name>` is the namespace of the repository, and `<digest>` 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`.
+
+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/<name>/manifests/<reference>`
+
+`<name>` refers to the namespace of the repository. `<reference>` MUST be either (a) the digest of the manifest or (b) a tag name.
+
+The `<reference>` 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