Engine API & Clients

### The daemon is a web server Docker is a client/server system. `dockerd` is the long-running daemon that owns images, containers, networks and volumes; the `docker` binary you type at is a *client* that holds none of that logic. Between them sits the Docker Engine API: a JSON-over-HTTP API that `dockerd` serves, by default, on the unix socket `/var/run/docker.sock`. Every container you have ever started was started by an HTTP request. Two consequences follow immediately. First, the `docker` binary is not where the interesting behaviour lives — it is a small HTTP client, and its power comes entirely from being able to open that socket. Second, anything else that can open the socket has the same power: Compose, build tooling, CI agents, monitoring agents, IDE plugins and your own shell scripts are all peers of the CLI, speaking one API. ### The shape of a request Because the transport is a unix socket there is no host to address. `curl` needs `--unix-socket`, and then any hostname at all, which it ignores: ``` curl -s --unix-socket /var/run/docker.sock http://localhost/v1.43/containers/json ``` Paths are prefixed with an API version. Bodies are JSON and a POST needs `Content-Type: application/json` — omit it and the daemon rejects the request rather than guessing. Options a CLI user passes as flags appear as JSON fields or query parameters: `docker ps -a` is `GET /containers/json?all=true`, and a status filter is a URL-encoded JSON map in the `filters` parameter. The endpoint families track the CLI's nouns — `/containers`, `/images`, `/networks`, `/volumes`, `/exec` — plus `/version`, `/info`, `/_ping`, `/events` and `/build`. ### What `docker run` actually is `docker run -d php:8.3-fpm` looks atomic and is not. The client performs: 1. `POST /containers/create`, with the image, command, environment and a `HostConfig` object carrying the host-level settings (mounts, port bindings, resource limits). Success is `201 Created` with an `Id`. 2. If that returns `404` because the image is not present locally, the CLI issues `POST /images/create?fromImage=php&tag=8.3-fpm` and retries. The API never pulls implicitly; the automatic pull is a client convenience. 3. `POST /containers/{id}/start`. 4. In the foreground case, an attach or logs call plus `POST /containers/{id}/wait` to learn the exit code. Knowing this decomposition is what makes API-level debugging possible. When `docker run` fails you can say whether creation, the pull or the start failed, because they are separate calls with separate status codes — `201` created, `404` no such image, `409` name already in use, `500` when the runtime refuses to start the process. ### Streaming endpoints Some endpoints do not return once. `GET /events`, `GET /containers/{id}/logs?follow=1`, `GET /containers/{id}/stats`, `POST /images/create` and `POST /build` hold the response open and stream — newline-delimited JSON progress objects for pulls and builds, framed byte chunks for logs and attach. A subtlety that catches people writing their own clients: a pull or a build answers `200 OK` as soon as it *starts*, and a failure arrives later *inside* the stream, as an object carrying an `errorDetail` field. A client that only checks the HTTP status will report a failed build as a success. Attach and exec go further: after the response headers the connection is hijacked and stops being HTTP, becoming a bidirectional byte stream. ### Clients and SDKs Docker publishes SDKs for Go (`github.com/docker/docker/client`) and Python (`docker`), and community libraries exist for other languages; all of them are wrappers over these HTTP calls. Choosing an SDK over shelling out to the CLI buys structured errors, no output parsing, correct handling of the streaming endpoints, and version negotiation. Shelling out buys familiarity and adds a dependency on human-readable output that changes between releases. ### There is no login The API has no username and password. On a default Linux install the socket file is owned by `root` with group `docker` and group write permission, so group membership is the whole access-control story and requests arrive at the daemon unauthenticated. That is exactly why exposing this API is treated as a security subject in its own right. ### What an interviewer is testing That you know the CLI is a thin client, that the socket carries ordinary HTTP, and that you could reach for `curl` when the CLI is unavailable or is hiding something — for example to see the exact `HostConfig` JSON a tool sent, or when writing an agent that must not shell out to a binary.