Painless Docker - 2nd Edition

Docker API: Hello World

In the following section, we're going to see how to use the Docker API to create a container and run it. We're going to use the following methods:

• HTTP REST API
• Python SDK

REST API

The first thing to check before using the REST API is to verify your API version. You can do this by running the following command:

docker version | grep -i "API version"

The version used in this example is 1.52. If you have 1.44 or higher, you can typically use the same commands by changing the version number in the URL.

We can export the API version to a variable for easier use:

export v="v1.52"

If you don't have curl and jq installed, you can install them using the following commands:

apt update && apt install -y curl jq

Using the REST API, we can pull an image:

curl \
--unix-socket /var/run/docker.sock \
-X POST http://localhost/$v/images/create?fromImage=alpine:latest

We can also create a container using the following command:

curl \
--unix-socket /var/run/docker.sock \
-H "Content-Type: application/json" \
-d '{"Image": "alpine", "Cmd": ["tail", "-f", "/dev/null"]}' \
-X POST http://localhost/$v/containers/create?name=test-container

This curl command creates a container named test-container using the Alpine image and runs the command tail -f /dev/null in the container. The container will be created in the stopped state. To start the container, we can use the following command:

curl \
--unix-socket /var/run/docker.sock \
-X POST http://localhost/$v/containers/test-container/start

To verify that the container is running, we can use the following command:

curl \
--unix-socket /var/run/docker.sock \
-X GET http://localhost/$v/containers/test-container/json | jq .

You should see that the container is in the "Running" state:

"status": "running",

Remove the container when you are done:

curl \
--unix-socket /var/run/docker.sock \
-X DELETE http://localhost/$v/containers/test-container?force=true

Python SDK

Let's do the same thing using the Python SDK. Start by removing the container we created in the previous section:

docker rm -f test-container

First, we need to run the following commands:

mkdir -p $HOME/container-test-python && cd $HOME/container-test-python

# Install some dependencies
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install \
    python3.14 \
    python3.14-venv \
    python3.14-dev \
    python3-pip -y

# Create a Python virtual environment
python3.14 -m venv .venv
source .venv/bin/activate

# Install the Docker SDK for Python
pip install docker==7.1.0

Execute the following command to create a Python program that creates a container and starts it:

cat <<EOF > run.py
import docker

# Create a Docker client
client = docker.from_env()

# Pull the Alpine image (if not already present)
client.images