distribution / distribution

What is Registry API?

The Registry API is a set of RESTful APIs that define how to interact with a container registry. This API is used by tools and applications to manage container images, tags, and manifests. It provides a standardized way for developers to interact with container registries.

Why is Registry API important?

The Registry API is essential for:

  • Building and distributing container images: The API allows developers to push and pull container images to and from registries.
  • Managing container image repositories: The API supports operations like listing images, creating and deleting repositories, and managing tags.
  • Authenticating and authorizing access: The API enables secure access control for container image repositories.
  • Integrating with CI/CD pipelines: The API facilitates automated image building, pushing, and pulling as part of a continuous integration and continuous delivery process.

Registry API Versions

The Registry API has evolved over time, with different versions supporting varying functionalities. The most commonly used version is the v2 API.

Registry API v2

The Registry API v2 is the latest version of the API and provides a robust set of features for managing container images. It offers functionalities such as:

  • Pushing and pulling images: The API defines the operations for uploading and downloading container images.
  • Tagging images: The API allows developers to create and manage tags for images, enabling versioning and easy referencing.
  • Manifests and Layers: The API defines how to retrieve and manage the manifest, which describes the image and its layers.
  • Authorization and Authentication: The API supports different authentication mechanisms and provides a framework for authorizing access to repositories.
  • Repository Management: The API includes operations for creating, deleting, and managing repositories, including namespace support.

API Endpoints

The Registry API v2 uses a set of endpoints to access various functionalities. Some key endpoints include:

  • /v2/: This is the base endpoint for all Registry API v2 operations.
  • /v2/<namespace>/<repository>/manifests/<reference>: This endpoint is used to retrieve the manifest for a specific image.
  • /v2/<namespace>/<repository>/blobs/<digest>: This endpoint is used to retrieve a specific layer of the image.
  • /v2/<namespace>/<repository>/tags/<tag>: This endpoint is used to manage tags associated with a repository.

Example Interactions

Here are some examples of common interactions with the Registry API:

  • Pushing an image: “` curl -X PUT -H “Content-Type: application/tar” –data-binary @image.tar
    https://registry.example.com/v2/namespace/repository/manifests/sha256:1234567890abcdef
  • Pulling an image: 
    curl -X GET -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
            https://registry.example.com/v2/namespace/repository/manifests/sha256:1234567890abcdef
  • Listing tags for a repository:
    curl -X GET \
            https://registry.example.com/v2/namespace/repository/tags/list
  • Deleting a tag:
    curl -X DELETE \
            https://registry.example.com/v2/namespace/repository/tags/latest

Note: Replace the placeholders in these examples with your actual namespace, repository name, image digest, and tag names.

Reference

Top-Level Directory Explanations

cmd/ - This directory contains the command-line interface (CLI) for the distribution project. It includes various subdirectories and files for different commands such as digest, registry, and others.

cmd/digest/ - This subdirectory is related to the digest command, which is used to compute and verify the integrity of Git objects using various algorithms.

digestset/ - This directory is related to the digestset package, which is used to manage a set of Git object digests. It includes a deprecated file and other Go files.

health/ - This directory is related to the health checking functionality of the distribution project. It includes files for API, checks, and documentation.

registry/ - This directory is related to the GitHub Package Registry functionality of the distribution project. It includes various subdirectories for API, auth, handlers, listener, middleware, proxy, storage, and more.

Entrypoints and Where to Start

cmd/digest/main.go - Entry point for the digest command with functions for initialization, usage, handling unsupported types, and the main function.

cmd/registry-api-descriptor-template/main.go - Entry point for the registry-api-descriptor-template command, which uses the APIDescriptor from the api/v2 package to execute templates passed through the command line. The command generates new API specifications using the provided template and the APIDescriptor object. The template syntax is based on Go’s standard library text/template package. For more information on the template syntax, please refer to golang.org/pkg/text/template.