github.com/moby/moby/api

Purpose

The api module is a pure-data Go package: request/response types and the OpenAPI/Swagger definition of the Engine API. It is consumed by both the daemon (as a vendored dependency) and the client module, plus any third-party tool that needs the wire types.

Layout

api/
├── go.mod                # Module: github.com/moby/moby/api
├── swagger.yaml          # Source of truth for the HTTP API (467 KB)
├── swagger-gen.yaml      # Code generator config
├── README.md             # Workflow for editing the API
├── docs/                 # CHANGELOG.md, version-history.md
├── types/                # Hand-written Go types per resource group
├── pkg/                  # Tiny utilities (e.g. progress reader)
├── validate/             # API-version comparison helpers
├── templates/            # go-swagger templates
├── scripts/              # Swagger codegen scripts
└── releases/             # Tag-tracking metadata

Type packages

Each resource has its own subpackage under api/types/:

Package	Examples
types/container/	Config, HostConfig, Health, State, Stats, ExecCreateRequest.
types/image/	Summary, History, LoadResponse, manifest types.
types/network/	EndpointSettings, IPAMConfig, CreateRequest.
types/volume/	Volume, CreateOptions, ClusterVolume*.
types/build/	Build request/response, prune.
types/swarm/	Service, Task, Node, Secret, Config.
types/registry/	Auth payloads, search results, distribution descriptors.
types/system/	Info, Version, Event, DiskUsage.
types/plugin/	Plugin manifest and runtime config.
types/checkpoint/	Checkpoint create/list/remove (CRIU experimental).
types/events/	Streaming event message.
types/storage/	Container fs change records.
types/blkiodev/	Block IO throttle entries used in HostConfig.
types/jsonstream/	The streaming {status, progressDetail, ...} envelope used by pull/push/build.
types/auxprogress/	Auxiliary progress messages emitted alongside the main stream.
types/strslice/	The StrSlice JSON helper (string-or-array decoding).
types/common/	IDResponse, ErrorResponse, version constants.
types/mount/	Mount spec for --mount.

swagger.yaml

The Swagger document is the contract. From README.md: "The API is defined by the Swagger definition in api/swagger.yaml." Tools generated from it include the API docs site, machine-readable schemas, and (partially) the Go types.

The file is split into:

• definitions: — reusable objects.
• paths: — endpoints.

Edits go through make swagger-gen (regenerate types) and make swagger-docs (preview HTML). make validate-swagger enforces correctness.

CHANGELOG

Per-version API differences are tracked in api/docs/CHANGELOG.md. Whenever you bump the API version constant, add an entry here.

Releasing

The api/ module is tagged independently as api/v1.x.x. Tag dates and release notes live in api/releases/. The client module tags follow a similar pattern.

How the daemon uses it

The daemon vendors github.com/moby/moby/api and converts between API types and internal domain types in:

• daemon/cluster/convert/ (swarm).
• Inline conversions throughout daemon/ for containers, images, networks, volumes.

Stability

The README is explicit:

The supported public Go modules are github.com/moby/moby/client and github.com/moby/moby/api.

The api types are versioned via the module tag. Field additions are non-breaking; field removals or renames bump the major.

See also

• client — Go HTTP client built on these types.
• API endpoints — wiki overview of what each endpoint does.
• api/README.md for the editor workflow.