Docker Engine API 1.57 moves its source specification to OpenAPI 3.2
Docker changes its API source format and adds a useful signal for detecting pending container restarts.
The socket is not the risky part, the tooling around it is
If you generate clients, validate schemas, or run automation against the Docker socket, this release deserves a look. Docker Engine API 1.57 changes the source format of its specification from Swagger 2.0 to OpenAPI 3.2. Existing API integrations do not suddenly need a rewrite, but any part of your workflow that downloads and processes the API contract may need updating. (github.com)
This matters most for homelab scripts, internal dashboards, workers, and services that create clients from a definition file. Docker still publishes a generated Swagger 2.0 specification as a transition path. It also ships a Swagger copy pinned to API version 1.57, but future API versions will no longer include those per-version Swagger files. (github.com)
What changes in the specification
Docker’s source-of-truth file is now api/openapi.yaml, using OpenAPI 3.2. If your tooling supports it, the sensible move is to consume that file directly instead of relying on version-specific Swagger copies. If you still need Swagger 2.0, use the generated document while you update the generator, validator, or library in your stack. (github.com)
I would not make this change blindly in automation that controls important services or production workloads. I would regenerate the client in a separate branch, compare the resulting types, and check how the tool handles references, reused schemas, and generated model names. The API behavior is not the main concern here; the concern is how each tool interprets the new source document.
Check the negotiated version first
Docker’s API is versioned, and the client and daemon can negotiate a common version. Before forcing API 1.57 from a client, check which maximum version the target daemon actually supports. Docker also documents DOCKER_API_VERSION, but setting it disables automatic version negotiation, so I would keep it for a specific compatibility case or for debugging. (docs.docker.com)
docker version
DOCKER_API_VERSION=1.57 docker versionIf the server does not support API 1.57, that environment variable does not make it compatible. When a Laravel application, worker, or central automation service manages several Docker hosts, detect the server version before relying on recently added behavior. Backward compatibility is useful, but features introduced in newer versions are disabled when an older API version is negotiated. (docs.docker.com)
A more useful signal for restart monitoring
The other practical change is in container die events. When Docker expects a container to restart, the event includes a restarting attribute set to "true". That can happen because of a restart policy or a manual restart, making it easier to distinguish a final exit from a container that is entering a recovery cycle. (github.com)
Before wiring this into an API consumer, I can inspect the event stream from the CLI. Docker supports filtering events by object type and event action, and docker events can emit one JSON object per line. (docs.docker.com)
docker events \
--filter 'type=container' \
--filter 'event=die' \
--format jsonA process reading that stream can inspect the event attributes and treat restarting=true as an early warning. In a Laravel-based setup, I might log the incident, delay a dependent job, or temporarily mark a service as unavailable. I would not treat it as proof that the container is healthy again: wait for a later signal or query the actual container state.
The small print matters
restarting=true signals an intended restart, not a guaranteed one. The restart may still be cancelled or fail, so it is not a safe trigger for irreversible actions. The attribute is omitted when the container will not restart, including when the daemon is shutting down. (github.com)
It is not a replacement for application readiness checks either. A container can be running again while the application is still booting, running migrations, or waiting on a failed dependency. If a workflow needs to know when work can resume, combine Docker events with health checks, an HTTP probe, or whatever readiness signal the service exposes.
What I would review now
I would search for references to swagger.yaml, version-pinned specification files, and generators locked to Swagger 2.0. Then I would test OpenAPI 3.2 locally, regenerate the client, and compare the result before updating deployed automation. If a project does not generate anything from the API specification, this change is unlikely to require immediate work. (github.com)
I would also add an integration test around restart events if the system reacts to them. Testing only that a die event arrives is not enough: cover restarting=true, the case where the attribute is absent, and the point where the container is genuinely available again. That is a small amount of work, but it prevents an intended recovery from being mistaken for a completed one.
Official Docker Engine API 1.57 source Official Docker Engine API documentation