moby/moby/api

The independently-versioned Go module of shared request/response types for the Docker Engine API, used by both the daemon and third-party Go clients.

Library
Go
vv1.56.1
72,352 stars
Apache License 2.0

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
97 /100 Excellent
Development Activity 96
Maintenance 96
Community 96
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
77 /100 Good
Architecture 80
Code Quality 78
Innovation 58
Learning Curve 90

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.

Used by 23 apps in this directory

Go
90%
BSD 3

tau

Devops

5,165

Open-source, Git-native platform-as-a-service for building, deploying, and scaling fullstack apps on your own infrastructure with no DevOps required.

View details
66
Repo Health
82
Technical
65
Dependency
Built with
Go 90%
Updated 2 weeks ago
Go
75%
AGPL 3.0

Teleport

Authentication · Security

21,074

Zero-trust infrastructure access platform that replaces credentials and VPNs with short-lived certificates, SSO, and identity-aware proxies for SSH, Kubernetes, databases, RDP, and AI agents.

View details
94
Repo Health
81
Technical
68
Dependency
Built with
Go 75%
TypeScript 16%
Updated 1 weeks ago
Go
75%
AGPL 3.0

Teleport

Authentication · Security

21,074

Zero-trust infrastructure access platform that replaces credentials and VPNs with short-lived certificates, SSO, and identity-aware proxies for SSH, Kubernetes, databases, RDP, and AI agents.

View details
94
Repo Health
81
Technical
68
Dependency
Built with
Go 75%
TypeScript 16%
Updated 1 weeks ago
Go
94%
MIT

Traefik

Automation · Devops · Security

65,483

A cloud-native reverse proxy and load balancer that auto-configures itself from Docker, Kubernetes, and other orchestrators — zero manual routing required.

View details
93
Repo Health
85
Technical
64
Dependency
Built with
Go 94%
Updated 1 weeks ago
Go
94%
MIT

Traefik

Automation · Devops · Security

65,483

A cloud-native reverse proxy and load balancer that auto-configures itself from Docker, Kubernetes, and other orchestrators — zero manual routing required.

View details
93
Repo Health
85
Technical
64
Dependency
Built with
Go 94%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers