API de Docker Engine

Docker proporciona una API para interactuar con el demonio de Docker (llamada API de Docker Engine), así como SDKs para Go y Python. Los SDKs te permiten compilar y escalar de manera eficiente aplicaciones y soluciones de Docker. Si Go o Python no se adaptan a tus necesidades, puedes usar la API de Docker Engine directamente.

Para obtener información sobre los SDKs de Docker Engine, consulta Desarrollar con los SDKs de Docker Engine.

La API de Docker Engine es una API RESTful a la que se accede mediante un cliente HTTP como wget o curl, o la biblioteca HTTP que forma parte de la mayoría de los lenguajes de programación modernos.

Ver la referencia de la API

Puedes ver la referencia de la última versión de la API o elegir una versión específica.

API y SDK con versiones

La versión de la API de Docker Engine que debes usar depende de la versión de tu demonio de Docker y de tu cliente de Docker.

Una versión dada del SDK de Docker Engine es compatible con una versión específica de la API de Docker Engine, así como con todas las versiones anteriores. Si ocurren cambios incompatibles (breaking changes), se documentan de forma destacada.

Note

El demonio y el cliente de Docker no necesariamente tienen que ser de la misma versión en todo momento. Sin embargo, ten en cuenta lo siguiente:

• Si el demonio es más nuevo que el cliente, el cliente no conocerá las nuevas características o los puntos de conexión de la API obsoletos en el demonio.
• Si el cliente es más nuevo que el demonio, el cliente puede solicitar puntos de conexión de la API que el demonio no conoce.

Se lanza una nueva versión de la API cuando se añaden nuevas características. La API de Docker es retrocompatible, por lo que no necesitas actualizar el código que utiliza la API a menos que necesites aprovechar las nuevas características.

Para ver la versión más alta y más baja de la API que admiten tu demonio y cliente de Docker, utiliza docker version:

$ docker version
Client: Docker Engine - Community
 Version:           29.5.1
 API version:       1.54
 ...

Server: Docker Engine - Community
 Engine:
  Version:          29.5.1
  API version:      1.54 (minimum version 1.40)
  ...

Puedes especificar la versión de la API a utilizar de cualquiera de las siguientes maneras:

• Al utilizar el SDK, usa la última versión. Como mínimo, utiliza la versión que incorpore la versión de la API con las características que necesitas.

• Al utilizar curl directamente, especifica la versión como la primera parte de la URL. Por ejemplo, si el punto de conexión es /containers/, puedes usar /v1.54/containers/.

• Para forzar a la CLI de Docker o a los SDKs de Docker Engine a utilizar una versión anterior de la API que la versión reportada por docker version, establece la variable de entorno DOCKER_API_VERSION con la versión correcta. Esto funciona en clientes de Linux, Windows y macOS.

  $ DOCKER_API_VERSION=1.53
  

  Mientras la variable de entorno esté establecida, se utilizará esa versión de la API, incluso si el demonio de Docker admite una versión más nueva. Esta variable de entorno desactiva la negociación de la versión de la API, por lo que solo debes usarla si debes utilizar una versión específica de la API, o para fines de depuración.

• El SDK de Go para Docker te permite habilitar la negociación de versión de la API, seleccionando automáticamente una versión de la API que sea compatible tanto con el cliente como con el Docker Engine en uso.

• Para los SDKs, también puedes especificar la versión de la API de forma programada como un parámetro del objeto client. Consulta el constructor de Go o la documentación del SDK de Python para client.

Versión mínima de la API

El servidor de la API de Docker Engine y el cliente admiten la negociación de la versión de la API. Si un cliente se conecta a una versión anterior de Docker Engine, negocia la versión más alta de la API admitida tanto por el cliente como por el demonio, descendiendo a una versión anterior de la API si es necesario.

Al descender a una versión anterior de la API, las características introducidas en versiones posteriores de la API se desactivan, y las peticiones y respuestas de la API se ajustan para la versión de la API negociada.

La negociación de la versión de la API permite que las herramientas que aún no se han actualizar a la última especificación de la versión de la API se comuniquen con Docker Engines más nuevos (y viceversa), pero la compatibilidad se realiza en la medida de lo posible (best effort); aunque Docker se esfuerza por proporcionar una compatibilidad total, es posible que algunas funcionalidades no estén disponibles.

Matriz de versiones de la API

Versiones de la API obsoletas

Las versiones de la API anteriores a la v1.40 están obsoletas y ya no son compatibles con las versiones actuales de Docker Engine y de la CLI. Puedes encontrar la documentación archivada para las versiones obsoletas de la API en el repositorio de código en GitHub: