2.1.3 Engine API Layer

The Engine API layer is the complete set of HTTP endpoints exposed by the Docker daemon, organized around resources such as containers, images, networks, and volumes, each with its own set of routes for creating, inspecting, modifying, and removing that resource.

Resource-Oriented API Design

The API follows a resource-oriented structure: each kind of object Docker manages has its own family of endpoints, generally following REST conventions where the HTTP method indicates the action and the URL path indicates the resource.

curl --unix-socket /var/run/docker.sock http://localhost/containers/json
curl --unix-socket /var/run/docker.sock -X POST http://localhost/containers/create -d '{"Image":"nginx"}'

The first request lists containers; the second creates one, with the method and path together determining what action is performed.

Versioning the API

Every endpoint is implicitly or explicitly tied to an API version, allowing the daemon to support older clients while still evolving its capabilities, since the version segment of the URL determines which version of an endpoint's behavior is used.

curl --unix-socket /var/run/docker.sock http://localhost/v1.43/version

Discovering the API's Capabilities

The daemon reports its own supported API version and other capabilities through a dedicated endpoint, which clients use to confirm compatibility before issuing further requests.

curl --unix-socket /var/run/docker.sock http://localhost/version

Streaming Endpoints

Not every endpoint returns a single response immediately; endpoints related to logs, build output, or live event streams keep the connection open and send data incrementally as it becomes available.

curl --unix-socket /var/run/docker.sock http://localhost/containers/myapp/logs?follow=true&stdout=true

Why the API Layer's Structure Matters

Because the API is organized consistently around resources, learning how one family of endpoints works (such as containers) makes the structure of other families (images, networks, volumes) predictable, since they all follow the same underlying conventions for listing, creating, inspecting, and removing resources.