docker / cli

API Interactions

This section outlines how the Docker CLI interacts with the Docker API (via the docker daemon) to perform operations like container management, image building, and network manipulation. This involves exploring the client and api packages.

client package:

The client package provides the core functionality for interacting with the Docker API. It’s responsible for:

  • Establishing a connection: Connecting to the Docker daemon, handling authentication, and setting up the communication channel.
  • Sending requests: Creating and sending API requests to the Docker daemon, including operations related to containers, images, networks, and other resources.
  • Receiving and parsing responses: Processing the responses from the Docker daemon, handling errors, and extracting data.
  • Error handling: Identifying and handling potential errors during API interactions.

Example:

package client
          
          import (
              "context"
              "encoding/json"
              "fmt"
              "io"
              "net/http"
              "net/url"
              "strings"
          
              "github.com/docker/cli/cli/config"
              "github.com/docker/cli/cli/conn"
              "github.com/docker/cli/cli/context/docker/client"
              "github.com/docker/cli/cli/registry"
              "github.com/docker/cli/cli/streams"
              "github.com/docker/cli/cli/utils"
              "github.com/docker/cli/opts"
              "github.com/docker/docker/api/types"
              "github.com/docker/docker/api/types/versions"
              "github.com/docker/docker/api/types/versions/v1_24"
              "github.com/pkg/errors"
              "github.com/spf13/cobra"
              "github.com/spf13/pflag"
              "golang.org/x/net/context/ctxhttp"
          )
          
          // client is the interface used by the `docker` CLI to interact with the Docker API.
          type Client interface {
              // ...
              ImageBuild(ctx context.Context, options types.ImageBuildOptions) (types.ImageBuildResponse, error)
              // ...
          }
          
          // Client is the struct that holds the client's connection to the Docker API.
          type Client struct {
              // ...
              client *http.Client
              // ...
              config *config.Config
              // ...
          }
          
          // NewClient creates a new client instance.
          func NewClient(
              // ...
          ) (*Client, error) {
              // ...
          }
          
          // ImageBuild builds an image from a Dockerfile.
          func (cli *Client) ImageBuild(ctx context.Context, options types.ImageBuildOptions) (types.ImageBuildResponse, error) {
              // ...
          }

api package:

The api package defines the structures and functions for interacting with the Docker API endpoints. It provides:

  • Endpoint definitions: Defining the different API endpoints and their corresponding request and response formats.
  • API request builders: Creating API requests based on the endpoint definitions and provided parameters.
  • API response handlers: Parsing and validating the responses received from the Docker API.

Example:

package api
          
          import (
              "bytes"
              "context"
              "encoding/json"
              "fmt"
              "io"
              "io/ioutil"
              "net/http"
              "net/url"
              "strings"
          
              "github.com/docker/cli/cli/config"
              "github.com/docker/cli/cli/conn"
              "github.com/docker/cli/cli/streams"
              "github.com/docker/cli/cli/utils"
              "github.com/docker/cli/opts"
              "github.com/docker/docker/api/types"
              "github.com/docker/docker/api/types/versions"
              "github.com/docker/docker/api/types/versions/v1_24"
              "github.com/pkg/errors"
              "github.com/spf13/cobra"
              "github.com/spf13/pflag"
              "golang.org/x/net/context/ctxhttp"
          )
          
          // BuildImageFromReader builds an image from the provided reader.
          func BuildImageFromReader(
              // ...
          ) error {
              // ...
          }

Additional notes:

  • The client and api packages are part of the Docker CLI, which is a separate repository from the Docker Engine. https://github.com/docker/cli
  • The API interactions are based on the Docker API specification. https://docs.docker.com/engine/api/v1.41/
  • The Docker CLI uses the docker daemon to perform its operations. The daemon listens on a specific socket or TCP port for API requests.