API Endpoints for docker/docker-py

In the docker/docker-py codebase, defined routes are primarily found within specific modules responsible for managing different entities. The routes correspond to Docker API endpoints that allow interaction with various Docker objects. Below are key components and examples illustrating the defined routes.

Top-Level Routes

The primary entry point for API interaction in docker-py is the docker/api directory, which encapsulates different modules. Each of these modules corresponds to a specific aspect of Docker’s functionality.

Example: client.py

Inside client.py, routes are defined as methods under the APIClient class. Here’s an example of how routes are structured:

class APIClient:
...

def containers(self, all=False):
"""
Get a list of containers.
:param all: Include all containers (default: False).
:return: List of containers.
"""
return self._get('/containers/json', params={'all': all})

The method containers calls the _get method with the specified endpoint /containers/json. The parameters can be tailored according to the needs:

Example: containers.py

The containers functionality is fleshed out further in containers.py, which handles specific routes related to container operations.

class ContainerAPI(APIClient):
...

def create(self, **options):
"""
Create a container.
:param options: Options for container creation.
:return: Container details.
"""
return self._post('/containers/create', json=options)

In this method, a POST request is directed at the /containers/create endpoint, allowing the creation of new containers with the provided options.

Other Resource Routes

Beyond containers, other resources have corresponding modules with defined routes to interact with Docker services.

Example: images.py

The images.py file is dedicated to managing Docker images and contains routes such as:

class ImageAPI(APIClient):
...

def pull(self, repository, tag=None):
"""
Pull an image.
:param repository: Name of the image repository.
:param tag: Tag of the image (default: 'latest').
:return: Status of the pull request.
"""
return self._post('/images/create', params={'fromImage': repository, 'tag': tag or 'latest'})

This example illustrates how to pull images using the /images/create endpoint with appropriate parameters for the repository and tag.

Example: volumes.py

Functions related to managing volumes can be found in volumes.py, outlining routes such as:

class VolumeAPI(APIClient):
...

def create(self, name=None, **options):
"""
Create a volume.
:param name: Name of the volume.
:param options: Other options for volume creation.
:return: Volume details.
"""
return self._post('/volumes/create', json={'Name': name, **options})

In this case, the method communicates with the /volumes/create endpoint for creating new Docker volumes.

Networking Routes

Networking features are present in networks.py which includes routes for network management.

class NetworkAPI(APIClient):
...

def create(self, name, **options):
"""
Create a network.
:param name: Name of the network.
:param options: Other options for network creation.
:return: Network details.
"""
return self._post('/networks/create', json={'Name': name, **options})

The /networks/create endpoint allows users to define and create new Docker networks.

Summary

The defined routes in docker/docker-py provide a comprehensive API for interacting with Docker components such as containers, images, volumes, and networks. Each module encapsulates related functionality and allows for a structured and coherent method of invoking the underlying Docker API.

Source: docker/docker-py repository