README

Working on the Engine API

The Engine API is an HTTP API used by the command-line client to communicate with the daemon. It can also be used by third-party software to control the daemon.

It consists of various components in this repository:

  • api/swagger.yaml A Swagger definition of the API.
  • api/types/ Types shared by both the client and server, representing various objects, options, responses, etc. Most are written manually, but some are automatically generated from the Swagger definition. See #27919 for progress on this.
  • cli/ The command-line client.
  • client/ The Go client used by the command-line client. It can also be used by third-party Go programs.
  • daemon/ The daemon, which serves the API.

## Swagger definition

The API is defined by the Swagger definition in api/swagger.yaml. This definition can be used to:

  1. To automatically generate documentation.
  2. To automatically generate the Go server and client. (A work-in-progress.)
  3. Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc.

Updating the API documentation

The API documentation is generated entirely from api/swagger.yaml. If you make updates to the API, you'll need to edit this file to represent the change in the documentation.

The file is split into two main sections:

  • definitions, which defines re-usable objects used in requests and responses
  • paths, which defines the API endpoints (and some inline objects which don't need to be reusable)

To make an edit, first look for the endpoint you want to edit under paths, then make the required edits. Endpoints may reference reusable objects with $ref, which can be found in the definitions section.

There is hopefully enough example material in the file for you to copy a similar pattern from elsewhere in the file (e.g. adding new fields or endpoints), but for the full reference, see the Swagger specification

swagger.yaml is validated by hack/validate/swagger to ensure it is a valid Swagger definition. This is useful for when you are making edits to ensure you are doing the right thing.

Viewing the API documentation

When you make edits to swagger.yaml, you may want to check the generated API documentation to ensure it renders correctly.

All the documentation generation is done in the documentation repository, docker/docker.github.io. The Swagger definition is vendored periodically into this repository, but you can manually copy over the Swagger definition to test changes.

Copy api/swagger.yaml in this repository to engine/api/[VERSION_NUMBER]/swagger.yaml in the documentation repository, overwriting what is already there. Then, run docker-compose up in the documentation repository and browse to http://localhost:4000/engine/api/ when it finishes rendering.

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const (
	// DefaultVersion of Current REST API
	DefaultVersion string = "1.26"

	// NoBaseImageSpecifier is the symbol used by the FROM
	// command to specify that no base image is to be used.
	NoBaseImageSpecifier string = "scratch"
)

    Common constants for daemon and client.

    View Source
    const MinVersion string = "1.12"

      MinVersion represents Minimum REST API version supported

      Variables

      This section is empty.

      Functions

      func DisplayablePorts

      func DisplayablePorts(ports []types.Port) string

        DisplayablePorts returns formatted string representing open ports of container e.g. "0.0.0.0:80->9090/tcp, 9988/tcp" it's used by command 'docker ps'

        func LoadOrCreateTrustKey

        func LoadOrCreateTrustKey(trustKeyPath string) (libtrust.PrivateKey, error)

          LoadOrCreateTrustKey attempts to load the libtrust key at the given path, otherwise generates a new one

          func MatchesContentType

          func MatchesContentType(contentType, expectedType string) bool

            MatchesContentType validates the content type against the expected one

            Types

            This section is empty.

            Directories

            Path Synopsis
            Package types is used for API stability in the types and response to the consumers of the API stats endpoint.
            Package types is used for API stability in the types and response to the consumers of the API stats endpoint.
            backend
            Package backend includes types to send information to server backends.
            Package backend includes types to send information to server backends.
            filters
            Package filters provides helper function to parse and handle command line filter, used for example in docker ps or docker images commands.
            Package filters provides helper function to parse and handle command line filter, used for example in docker ps or docker images commands.
            versions/v1p19
            Package v1p19 provides specific API types for the API version 1, patch 19.
            Package v1p19 provides specific API types for the API version 1, patch 19.
            versions/v1p20
            Package v1p20 provides specific API types for the API version 1, patch 20.
            Package v1p20 provides specific API types for the API version 1, patch 20.