moby/moby/api

github.com/moby/moby/api is the Go module that defines the data contracts for the Docker Engine API — the HTTP API the Docker CLI, the official client module, and third-party tools use to talk to the dockerd daemon. It lives inside the moby/moby monorepo but ships as its own SemVer-tagged module (api/vX.Y.Z) precisely so consumers can pin to a stable set of types without importing the entire container engine codebase.

The package is organized around Docker’s core objects — containers, images, networks, volumes, swarm services, plugins, checkpoints, and build/registry operations — each as its own subpackage under types/, mirroring the shape of api/swagger.yaml, which remains the canonical source of truth for the API surface. A small pkg/ directory adds concrete helpers on top of the raw types, such as stdcopy for demultiplexing the combined stdout/stderr stream Docker uses for container logs and exec output, and authconfig for decoding the base64-encoded X-Registry-Auth header used in registry operations.

Because this module was split out from github.com/docker/docker (the older, now-deprecated import path) as part of the Docker Engine v29 restructuring, it exists to give the Go ecosystem a lighter, purpose-built dependency: anything that needs to marshal/unmarshal Docker Engine API requests and responses — orchestrators, CI tooling, container inspection utilities — can import just this module instead of the full daemon.

What You Get

• Per-domain type packages — types/container, types/image, types/network, types/volume, types/swarm, types/plugin, types/checkpoint, types/registry, types/build, types/system, types/events — covering every Engine API object.
• pkg/stdcopy — a demultiplexer for Docker’s combined stdout/stderr stream format, used when reading container logs or exec output over the API.
• pkg/authconfig — decodes and validates the base64-encoded X-Registry-Auth header sent for image pull/push authentication.
• MediaType constants (types.MediaTypeRawStream, types.MediaTypeMultiplexedStream, types.MediaTypeJSON, types.MediaTypeNDJSON, etc.) for correctly interpreting streaming API responses.
• A swagger.yaml OpenAPI/Swagger definition plus per-version changelog docs (docs/v1.0.md through the current version) documenting exactly what changed release to release.

Common Use Cases

• Third-party Go tools that talk directly to the Docker Engine API (container orchestrators, CI runners, inspection/monitoring utilities) import these types to build and parse requests without depending on the full moby/moby daemon codebase.
• Building a custom Docker API client (or extending the official github.com/moby/moby/client module) that needs strongly-typed request/response structs instead of raw JSON.
• Demultiplexing container log or docker exec output streams fetched over the API using pkg/stdcopy.StdCopy.
• Decoding registry authentication headers when implementing a proxy, gateway, or custom server that speaks the Docker Engine API protocol.

Under The Hood

Architecture The module has no runtime logic of its own — it is a pure data-contract layer, organized as one type package per Docker domain object (container, image, network, volume, swarm, plugin, checkpoint, registry, build, system) sitting alongside a pkg/ directory of small, focused helper packages (stdcopy, authconfig) that operate on those types. The canonical source of truth is api/swagger.yaml, a ~14,000-line Swagger/OpenAPI definition; per the module’s own README, some Go structs are generated from it and most are still hand-maintained, an acknowledged and tracked gap (moby/moby#27919). Changing the wire protocol means editing the Swagger file first and propagating the change into the corresponding struct in types/, which keeps the module’s structure flat and predictable but places the burden of consistency on contributors and the validate/yamllint tooling rather than a fully generated pipeline.

Tech Stack The module targets Go 1.24 and carries a deliberately small dependency footprint for a types package: github.com/docker/go-units for size/duration formatting, github.com/moby/docker-image-spec and github.com/opencontainers/image-spec/go-digest for OCI image-spec interoperability, with gotest.tools/v3 and pgregory.net/rapid (property-based testing) as test-only dependencies. It is versioned and tagged independently from the rest of the moby/moby repository (api/vX.Y.Z tags, separate from client/vX.Y.Z and the docker-vX.Y.Z daemon release tags), and its documentation is built via a Makefile/Dockerfile pipeline that renders the Swagger spec into browsable API docs.

Code Quality Test coverage is concentrated on the packages with actual logic rather than the plain struct definitions: pkg/authconfig, pkg/stdcopy’s consumers, and several types/* files with custom marshaling or validation logic (container/hostconfig_test.go, container/config_test.go, container/health_test.go, swarm/network_test.go, jsonstream/message_test.go, network/port_test.go, network/hwaddr_test.go, plugin/capability_test.go) carry dedicated _test.go files using gotest.tools/v3 assertions, with pgregory.net/rapid used for property-based fuzzing in at least the plugin capability tests. Every exported type and constant carries a Go-doc comment explaining its origin (which API endpoint produces/consumes it) rather than just its shape, which is unusually thorough for a types package and reflects the module’s role as the authoritative reference for the wire format.

What Makes It Unique Most projects keep their API request/response types inline with their server implementation; this module deliberately extracts them into an independently-tagged, importable dependency specifically so the broader Go ecosystem (orchestrators, CLIs, monitoring tools) can depend on a stable Docker Engine API contract without pulling in the multi-hundred-thousand-line container engine itself. The recent split from the legacy github.com/docker/docker import path — with an explicit migration guide in the README — and independent SemVer versioning of api/ versus client/ versus the daemon release tags is a deliberate API-stability commitment that is uncommon among comparably large infrastructure projects.