distribution: github.com/docker/distribution/registry/api/v2 Index | Files

package v2

import "github.com/docker/distribution/registry/api/v2"

Package v2 describes routes, urls and the error codes used in the Docker Registry JSON HTTP API V2. In addition to declarations, descriptors are provided for routes and error codes that can be used for implementation and automatically generating documentation.

Definitions here are considered to be locked down for the V2 registry api. Any changes must be considered carefully and should not proceed without a change proposal in docker core.


Package Files

descriptors.go doc.go errors.go headerparser.go routes.go urls.go


const (
    RouteNameBase            = "base"
    RouteNameManifest        = "manifest"
    RouteNameTags            = "tags"
    RouteNameBlob            = "blob"
    RouteNameBlobUpload      = "blob-upload"
    RouteNameBlobUploadChunk = "blob-upload-chunk"
    RouteNameCatalog         = "catalog"

The following are definitions of the name under which all V2 routes are registered. These symbols can be used to look up a route based on the name.


var (
    ErrorCodeDigestInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:       "DIGEST_INVALID",
        Message:     "provided digest did not match uploaded content",
        Description: "" /* 301 byte string literal not displayed */,

        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeSizeInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:       "SIZE_INVALID",
        Message:     "provided length did not match content length",
        Description: "" /* 146 byte string literal not displayed */,

        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeNameInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "NAME_INVALID",
        Message: "invalid repository name",
        Description: `Invalid repository name encountered either during
		manifest validation or any API operation.`,
        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeTagInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "TAG_INVALID",
        Message: "manifest tag did not match URI",
        Description: `During a manifest upload, if the tag in the manifest
		does not match the uri tag, this error will be returned.`,
        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeNameUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "NAME_UNKNOWN",
        Message: "repository name not known to registry",
        Description: `This is returned if the name used during an operation is
		unknown to the registry.`,
        HTTPStatusCode: http.StatusNotFound,

    ErrorCodeManifestUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "MANIFEST_UNKNOWN",
        Message: "manifest unknown",
        Description: `This error is returned when the manifest, identified by
		name and tag is unknown to the repository.`,
        HTTPStatusCode: http.StatusNotFound,

    ErrorCodeManifestInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:       "MANIFEST_INVALID",
        Message:     "manifest invalid",
        Description: "" /* 225 byte string literal not displayed */,

        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeManifestUnverified = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "MANIFEST_UNVERIFIED",
        Message: "manifest failed signature verification",
        Description: `During manifest upload, if the manifest fails signature
		verification, this error will be returned.`,
        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeManifestBlobUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "MANIFEST_BLOB_UNKNOWN",
        Message: "blob unknown to registry",
        Description: `This error may be returned when a manifest blob is 
		unknown to the registry.`,
        HTTPStatusCode: http.StatusBadRequest,

    ErrorCodeBlobUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:       "BLOB_UNKNOWN",
        Message:     "blob unknown to registry",
        Description: "" /* 201 byte string literal not displayed */,

        HTTPStatusCode: http.StatusNotFound,

    ErrorCodeBlobUploadUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "BLOB_UPLOAD_UNKNOWN",
        Message: "blob upload unknown to registry",
        Description: `If a blob upload has been cancelled or was never
		started, this error code may be returned.`,
        HTTPStatusCode: http.StatusNotFound,

    ErrorCodeBlobUploadInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{
        Value:   "BLOB_UPLOAD_INVALID",
        Message: "blob upload invalid",
        Description: `The blob upload encountered an error and can no
		longer proceed.`,
        HTTPStatusCode: http.StatusNotFound,
var APIDescriptor = struct {
    // RouteDescriptors provides a list of the routes available in the API.
    RouteDescriptors []RouteDescriptor
    RouteDescriptors: routeDescriptors,

APIDescriptor exports descriptions of the layout of the v2 registry API.

func Router Uses

func Router() *mux.Router

Router builds a gorilla router with named routes for the various API methods. This can be used directly by both server implementations and clients.

func RouterWithPrefix Uses

func RouterWithPrefix(prefix string) *mux.Router

RouterWithPrefix builds a gorilla router with a configured prefix on all routes.

type BodyDescriptor Uses

type BodyDescriptor struct {
    ContentType string
    Format      string

BodyDescriptor describes a request body and its expected content type. For the most part, it should be example json or some placeholder for body data in documentation.

type MethodDescriptor Uses

type MethodDescriptor struct {

    // Method is an HTTP method, such as GET, PUT or POST.
    Method string

    // Description should provide an overview of the functionality provided by
    // the covered method, suitable for use in documentation. Use of markdown
    // here is encouraged.
    Description string

    // Requests is a slice of request descriptors enumerating how this
    // endpoint may be used.
    Requests []RequestDescriptor

MethodDescriptor provides a description of the requests that may be conducted with the target method.

type ParameterDescriptor Uses

type ParameterDescriptor struct {
    // Name is the name of the parameter, either of the path component or
    // query parameter.
    Name string

    // Type specifies the type of the parameter, such as string, integer, etc.
    Type string

    // Description provides a human-readable description of the parameter.
    Description string

    // Required means the field is required when set.
    Required bool

    // Format is a specifying the string format accepted by this parameter.
    Format string

    // Regexp is a compiled regular expression that can be used to validate
    // the contents of the parameter.
    Regexp *regexp.Regexp

    // Examples provides multiple examples for the values that might be valid
    // for this parameter.
    Examples []string

ParameterDescriptor describes the format of a request parameter, which may be a header, path parameter or query parameter.

type RequestDescriptor Uses

type RequestDescriptor struct {
    // Name provides a short identifier for the request, usable as a title or
    // to provide quick context for the particular request.
    Name string

    // Description should cover the requests purpose, covering any details for
    // this particular use case.
    Description string

    // Headers describes headers that must be used with the HTTP request.
    Headers []ParameterDescriptor

    // PathParameters enumerate the parameterized path components for the
    // given request, as defined in the route's regular expression.
    PathParameters []ParameterDescriptor

    // QueryParameters provides a list of query parameters for the given
    // request.
    QueryParameters []ParameterDescriptor

    // Body describes the format of the request body.
    Body BodyDescriptor

    // Successes enumerates the possible responses that are considered to be
    // the result of a successful request.
    Successes []ResponseDescriptor

    // Failures covers the possible failures from this particular request.
    Failures []ResponseDescriptor

RequestDescriptor covers a particular set of headers and parameters that can be carried out with the parent method. Its most helpful to have one RequestDescriptor per API use case.

type ResponseDescriptor Uses

type ResponseDescriptor struct {
    // Name provides a short identifier for the response, usable as a title or
    // to provide quick context for the particular response.
    Name string

    // Description should provide a brief overview of the role of the
    // response.
    Description string

    // StatusCode specifies the status received by this particular response.
    StatusCode int

    // Headers covers any headers that may be returned from the response.
    Headers []ParameterDescriptor

    // Fields describes any fields that may be present in the response.
    Fields []ParameterDescriptor

    // ErrorCodes enumerates the error codes that may be returned along with
    // the response.
    ErrorCodes []errcode.ErrorCode

    // Body describes the body of the response, if any.
    Body BodyDescriptor

ResponseDescriptor describes the components of an API response.

type RouteDescriptor Uses

type RouteDescriptor struct {
    // Name is the name of the route, as specified in RouteNameXXX exports.
    // These names a should be considered a unique reference for a route. If
    // the route is registered with gorilla, this is the name that will be
    // used.
    Name string

    // Path is a gorilla/mux-compatible regexp that can be used to match the
    // route. For any incoming method and path, only one route descriptor
    // should match.
    Path string

    // Entity should be a short, human-readalbe description of the object
    // targeted by the endpoint.
    Entity string

    // Description should provide an accurate overview of the functionality
    // provided by the route.
    Description string

    // Methods should describe the various HTTP methods that may be used on
    // this route, including request and response formats.
    Methods []MethodDescriptor

RouteDescriptor describes a route specified by name.

type URLBuilder Uses

type URLBuilder struct {
    // contains filtered or unexported fields

URLBuilder creates registry API urls from a single base endpoint. It can be used to create urls for use in a registry client or server.

All urls will be created from the given base, including the api version. For example, if a root of "/foo/" is provided, urls generated will be fall under "/foo/v2/...". Most application will only provide a schema, host and port, such as "https://localhost:5000/".

func NewURLBuilder Uses

func NewURLBuilder(root *url.URL, relative bool) *URLBuilder

NewURLBuilder creates a URLBuilder with provided root url object.

func NewURLBuilderFromRequest Uses

func NewURLBuilderFromRequest(r *http.Request, relative bool) *URLBuilder

NewURLBuilderFromRequest uses information from an *http.Request to construct the root url.

func NewURLBuilderFromString Uses

func NewURLBuilderFromString(root string, relative bool) (*URLBuilder, error)

NewURLBuilderFromString workes identically to NewURLBuilder except it takes a string argument for the root, returning an error if it is not a valid url.

func (*URLBuilder) BuildBaseURL Uses

func (ub *URLBuilder) BuildBaseURL() (string, error)

BuildBaseURL constructs a base url for the API, typically just "/v2/".

func (*URLBuilder) BuildBlobURL Uses

func (ub *URLBuilder) BuildBlobURL(ref reference.Canonical) (string, error)

BuildBlobURL constructs the url for the blob identified by name and dgst.

func (*URLBuilder) BuildBlobUploadChunkURL Uses

func (ub *URLBuilder) BuildBlobUploadChunkURL(name reference.Named, uuid string, values ...url.Values) (string, error)

BuildBlobUploadChunkURL constructs a url for the upload identified by uuid, including any url values. This should generally not be used by clients, as this url is provided by server implementations during the blob upload process.

func (*URLBuilder) BuildBlobUploadURL Uses

func (ub *URLBuilder) BuildBlobUploadURL(name reference.Named, values ...url.Values) (string, error)

BuildBlobUploadURL constructs a url to begin a blob upload in the repository identified by name.

func (*URLBuilder) BuildCatalogURL Uses

func (ub *URLBuilder) BuildCatalogURL(values ...url.Values) (string, error)

BuildCatalogURL constructs a url get a catalog of repositories

func (*URLBuilder) BuildManifestURL Uses

func (ub *URLBuilder) BuildManifestURL(ref reference.Named) (string, error)

BuildManifestURL constructs a url for the manifest identified by name and reference. The argument reference may be either a tag or digest.

func (*URLBuilder) BuildTagsURL Uses

func (ub *URLBuilder) BuildTagsURL(name reference.Named) (string, error)

BuildTagsURL constructs a url to list the tags in the named repository.

Package v2 imports 10 packages (graph) and is imported by 1316 packages. Updated 2019-03-04. Refresh now. Tools for package owners.