From 797daef4cc07999632bb556c8084a19be77dba6a Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Fri, 21 Feb 2020 12:10:09 +0000 Subject: [PATCH 1/9] fix Engine API toc --- _data/toc.yaml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/_data/toc.yaml b/_data/toc.yaml index a185eb5f5b..47f839c976 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -953,14 +953,12 @@ reference: path: /engine/reference/commandline/dockerd/ - sectiontitle: Application Programming Interfaces (APIs) section: - - sectiontitle: Docker Engine API + - sectiontitle: Docker Engine SDK and API section: - - path: /engine/api/ + - path: /develop/sdk/ title: Overview - - path: /engine/api/get-started/ + - path: /develop/sdk/examples/ title: Get started - - path: /engine/api/sdks/ - title: SDKs - path: /engine/api/latest/ title: v{{ site.latest_engine_api_version }} reference (latest) - sectiontitle: API reference by version From 1566e01673293bcf5434989f78b28dbbeeb7c1f2 Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Fri, 21 Feb 2020 16:44:41 +0000 Subject: [PATCH 2/9] Moved topics under engine/api/ --- _data/toc.yaml | 8 +- .../examples.md => engine/api/get-started.md | 2 +- engine/api/index.md | 271 ++++++++++++++++++ {develop => engine/api}/sdk/index.md | 50 ++-- 4 files changed, 300 insertions(+), 31 deletions(-) rename develop/sdk/examples.md => engine/api/get-started.md (99%) create mode 100644 engine/api/index.md rename {develop => engine/api}/sdk/index.md (93%) diff --git a/_data/toc.yaml b/_data/toc.yaml index 47f839c976..63b6c87edd 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -953,12 +953,14 @@ reference: path: /engine/reference/commandline/dockerd/ - sectiontitle: Application Programming Interfaces (APIs) section: - - sectiontitle: Docker Engine SDK and API + - sectiontitle: Docker Engine API section: - - path: /develop/sdk/ + - path: /engine/api/ title: Overview - - path: /develop/sdk/examples/ + - path: /engine/api/get-started/ title: Get started + - path: /engine/api/sdk/ + title: SDKs - path: /engine/api/latest/ title: v{{ site.latest_engine_api_version }} reference (latest) - sectiontitle: API reference by version diff --git a/develop/sdk/examples.md b/engine/api/get-started.md similarity index 99% rename from develop/sdk/examples.md rename to engine/api/get-started.md index f572545c59..0dcbaaabfb 100644 --- a/develop/sdk/examples.md +++ b/engine/api/get-started.md @@ -3,10 +3,10 @@ title: Examples using the Docker Engine SDKs and Docker API keywords: developing, api, sdk, developers, rest, curl, python, go redirect_from: - /engine/api/getting-started/ -- /engine/api/get-started/ - /engine/api/client-libraries/ - /engine/reference/api/remote_api_client_libraries/ - /reference/api/remote_api_client_libraries/ +- /develop/sdk/examples/ --- After you diff --git a/engine/api/index.md b/engine/api/index.md new file mode 100644 index 0000000000..1bd2462ed9 --- /dev/null +++ b/engine/api/index.md @@ -0,0 +1,271 @@ +--- +title: Develop with Docker Engine API +description: Using Docker APIs to automate Docker tasks in your language of choice +keywords: developing, api +redirect_from: +- /engine/reference/api/ +- /engine/reference/api/docker_remote_api/ +- /reference/api/ +- /reference/api/docker_remote_api/ +--- + +Docker provides an API for interacting with the Docker daemon (called the Docker +Engine API), as well as SDKs for Go and Python. The SDKs allow you to build and +scale Docker apps and solutions quickly and easily. If Go or Python don't work +for you, you can use the Docker Engine API directly. + +For information about Docker Engine SDKs, see [Develop with Docker Engine SDKs](/engine/api/sdk/). + +The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or +`curl`, or the HTTP library which is part of most modern programming languages. + +## View the API reference + +You can +[view the reference for the latest version of the API](/engine/api/latest/) +or [choose a specific version](/engine/api/version-history/). + +## Versioned API and SDK + +The version of the Docker Engine API you should use depends upon the version of +your Docker daemon and Docker client. + +A given version of the Docker Engine SDK supports a specific version of the +Docker Engine API, as well as all earlier versions. If breaking changes occur, +they are documented prominently. + +> Daemon and client API mismatches +> +> The Docker daemon and client do not necessarily need to be the same version +> at all times. However, keep the following in mind. +> +> - If the daemon is newer than the client, the client does not know about new +> features or deprecated API endpoints in the daemon. +> +> - If the client is newer than the daemon, the client can request API +> endpoints that the daemon does not know about. + +A new version of the API is released when new features are added. The Docker API +is backward-compatible, so you do not need to update code that uses the API +unless you need to take advantage of new features. + +To see the highest version of the API your Docker daemon and client support, use +`docker version`: + +```bash +$ docker version + +Client: + Version: 19.03.5 + API version: 1.40 + Go version: go1.12.12 + Git commit: 633a0ea + Built: Wed Nov 13 07:22:37 2019 + OS/Arch: windows/amd64 + Experimental: true + + +Server: + Version: 19.03.5 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.12 + Git commit: 633a0ea + Built: Wed Nov 13 07:29:19 2019 + OS/Arch: linux/amd64 + ... +``` + +You can specify the API version to use, in one of the following ways: + +- When using the SDK, use the latest version you can, but at least the version + that incorporates the API version with the features you need. + +- When using `curl` directly, specify the version as the first part of the URL. + For instance, if the endpoint is `/containers/`, you can use + `/v1.40/containers/`. + +- To force the Docker CLI or the Docker Engine SDKs to use an old version + version of the API than the version reported by `docker version`, set the + environment variable `DOCKER_API_VERSION` to the correct version. This works + on Linux, Windows, or macOS clients. + + ```bash + DOCKER_API_VERSION='1.40' + ``` + + While the environment variable is set, that version of the API is used, even + if the Docker daemon supports a newer version. + +- For the SDKs, you can also specify the API version programmatically, as a + parameter to the `client` object. See the + [Go constructor](https://github.com/moby/moby/blob/master/client/client.go#L136){: target="_blank" class="_"} + or the + [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html). + +### Docker Engine - Enterprise and Docker Engine - Community API mismatch + +If you use Docker Engine - Enterprise in production, we recommend using Docker Engine - Enterprise in development +too. If you can't, such as when your developers use Docker Desktop for Mac or Docker Desktop for +Windows and manually build and push images, then your developers need to configure +their Docker clients to use the same version of the API reported by their Docker +daemon. This prevents the developer from using a feature that is not yet supported +on the daemon where the workload runs in production. You can do this one of two ways: + +- Configure the Docker client to connect to an external daemon running Docker EE. + You can use the `-H` flag on the `docker` command or set the `DOCKER_HOST` + environment variable. The client uses the daemon's latest supported API version. +- Configure the Docker client to use a specific API by setting the `DOCKER_API_VERSION` + environment variable to the API version to use, such as `1.30`. + +### API version matrix + +Docker does not recommend running versions prior to 1.12, which means you +are encouraged to use an API version of 1.24 or higher. + +{% include api-version-matrix.md %} + +## SDK and API quickstart + +Use the following guidelines to choose the SDK or API version to use in your +code: + +- If you're starting a new project, use the + [latest version](/engine/api/latest/), but do specify the version you are + using. This helps prevent surprises. +- If you need a new feature, update your code to use at least the minimum version + that supports the feature, and prefer the latest version you can use. +- Otherwise, continue to use the version that your code is already using. + +As an example, the `docker run` command can be easily implemented using the +Docker API directly, or using the Python or Go SDK. + + +
+ +
+ +```go +package main + +import ( + "context" + "io" + "os" + + "github.com/docker/docker/api/types" + "github.com/docker/docker/api/types/container" + "github.com/docker/docker/client" + "github.com/docker/docker/pkg/stdcopy" +) + +func main() { + ctx := context.Background() + cli, err := client.NewClientWithOpts(client.FromEnv) + if err != nil { + panic(err) + } + cli.NegotiateAPIVersion(ctx) + + reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) + if err != nil { + panic(err) + } + io.Copy(os.Stdout, reader) + + resp, err := cli.ContainerCreate(ctx, &container.Config{ + Image: "alpine", + Cmd: []string{"echo", "hello world"}, + }, nil, nil, "") + if err != nil { + panic(err) + } + + if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { + panic(err) + } + + statusCh, errCh := cli.ContainerWait(ctx, resp.ID, container.WaitConditionNotRunning) + select { + case err := <-errCh: + if err != nil { + panic(err) + } + case <-statusCh: + } + + out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true}) + if err != nil { + panic(err) + } + + stdcopy.StdCopy(os.Stdout, os.Stderr, out) +} +``` + +
+
+ +```python +import docker +client = docker.from_env() +print client.containers.run("alpine", ["echo", "hello", "world"]) +``` + +
+
+ +```bash +$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \ + -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \ + -X POST http:/v1.24/containers/create +{"Id":"1c6594faf5","Warnings":null} + +$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start + +$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait +{"StatusCode":0} + +$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1" +hello world +``` + +
+
+ +For more examples, take a look at the +[Get started guide](/get-started.md). + +## Unofficial libraries + +There are a number of community supported libraries available for other +languages. They have not been tested by Docker, so if you run into any issues, +file them with the library maintainers. + +| Language | Library | +|:----------------------|:----------------------------------------------------------------------------| +| C | [libdocker](https://github.com/danielsuo/libdocker) | +| C# | [Docker.DotNet](https://github.com/ahmetalpbalkan/Docker.DotNet) | +| C++ | [lasote/docker_client](https://github.com/lasote/docker_client) | +| Dart | [bwu_docker](https://github.com/bwu-dart/bwu_docker) | +| Erlang | [erldocker](https://github.com/proger/erldocker) | +| Gradle | [gradle-docker-plugin](https://github.com/gesellix/gradle-docker-plugin) | +| Groovy | [docker-client](https://github.com/gesellix/docker-client) | +| Haskell | [docker-hs](https://github.com/denibertovic/docker-hs) | +| HTML (Web Components) | [docker-elements](https://github.com/kapalhq/docker-elements) | +| Java | [docker-client](https://github.com/spotify/docker-client) | +| Java | [docker-java](https://github.com/docker-java/docker-java) | +| Java | [docker-java-api](https://github.com/amihaiemil/docker-java-api) | +| NodeJS | [dockerode](https://github.com/apocas/dockerode) | +| NodeJS | [harbor-master](https://github.com/arhea/harbor-master) | +| Perl | [Eixo::Docker](https://github.com/alambike/eixo-docker) | +| PHP | [Docker-PHP](https://github.com/docker-php/docker-php) | +| Ruby | [docker-api](https://github.com/swipely/docker-api) | +| Rust | [docker-rust](https://github.com/abh1nav/docker-rust) | +| Rust | [shiplift](https://github.com/softprops/shiplift) | +| Scala | [tugboat](https://github.com/softprops/tugboat) | +| Scala | [reactive-docker](https://github.com/almoehi/reactive-docker) | +| Swift | [docker-client-swift](https://github.com/valeriomazzeo/docker-client-swift) | diff --git a/develop/sdk/index.md b/engine/api/sdk/index.md similarity index 93% rename from develop/sdk/index.md rename to engine/api/sdk/index.md index b3446e6397..78ecd08d0c 100644 --- a/develop/sdk/index.md +++ b/engine/api/sdk/index.md @@ -1,14 +1,10 @@ --- -title: Develop with Docker Engine SDKs and API -description: Using Docker SDKs and APIs to automate Docker tasks in your language of choice -keywords: developing, api, sdk +title: Develop with Docker Engine SDKs +description: Using Docker SDKs to automate Docker tasks in your language of choice +keywords: developing, sdk redirect_from: -- /engine/api/ -- /engine/reference/api/ -- /engine/reference/api/docker_remote_api/ -- /reference/api/ -- /reference/api/docker_remote_api/ - /engine/api/sdks/ +- /develop/sdk/ --- Docker provides an API for interacting with the Docker daemon (called the Docker @@ -84,21 +80,23 @@ To see the highest version of the API your Docker daemon and client support, use $ docker version Client: - Version: 17.04.0-ce - API version: 1.28 - Go version: go1.7.5 - Git commit: 4845c56 - Built: Wed Apr 5 06:06:36 2017 - OS/Arch: darwin/amd64 + Version: 19.03.5 + API version: 1.40 + Go version: go1.12.12 + Git commit: 633a0ea + Built: Wed Nov 13 07:22:37 2019 + OS/Arch: windows/amd64 + Experimental: true + Server: - Version: 17.04.0-ce - API version: 1.28 (minimum version 1.12) - Go version: go1.7.5 - Git commit: 4845c56 - Built: Tue Apr 4 00:37:25 2017 - OS/Arch: linux/amd64 - Experimental: true + Version: 19.03.5 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.12 + Git commit: 633a0ea + Built: Wed Nov 13 07:29:19 2019 + OS/Arch: linux/amd64 + ... ``` You can specify the API version to use, in one of the following ways: @@ -108,7 +106,7 @@ You can specify the API version to use, in one of the following ways: - When using `curl` directly, specify the version as the first part of the URL. For instance, if the endpoint is `/containers/`, you can use - `/v1.27/containers/`. + `/v1.40/containers/`. - To force the Docker CLI or the Docker Engine SDKs to use an old version version of the API than the version reported by `docker version`, set the @@ -116,7 +114,7 @@ You can specify the API version to use, in one of the following ways: on Linux, Windows, or macOS clients. ```bash - DOCKER_API_VERSION='1.27' + DOCKER_API_VERSION='1.40' ``` While the environment variable is set, that version of the API is used, even @@ -150,7 +148,7 @@ are encouraged to use an API version of 1.24 or higher. {% include api-version-matrix.md %} -### Choose the SDK or API version to use +## SDK and API quickstart Use the following guidelines to choose the SDK or API version to use in your code: @@ -162,8 +160,6 @@ code: that supports the feature, and prefer the latest version you can use. - Otherwise, continue to use the version that your code is already using. -## SDK and API quickstart - As an example, the `docker run` command can be easily implemented using the Docker API directly, or using the Python or Go SDK. @@ -265,7 +261,7 @@ hello world For more examples, take a look at the -[getting started guide](examples.md). +[Get started guide](/engine/api/get-started.md). ## Unofficial libraries From ee407ac0efbd199566c03ba7150ed962a1a23312 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:40:45 +0100 Subject: [PATCH 3/9] Move SDK examples under "sdk" Signed-off-by: Sebastiaan van Stijn --- _data/toc.yaml | 4 ++-- engine/api/index.md | 3 +-- engine/api/{get-started.md => sdk/examples.md} | 0 engine/api/sdk/index.md | 3 +-- 4 files changed, 4 insertions(+), 6 deletions(-) rename engine/api/{get-started.md => sdk/examples.md} (100%) diff --git a/_data/toc.yaml b/_data/toc.yaml index 63b6c87edd..9f43af03e8 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -957,10 +957,10 @@ reference: section: - path: /engine/api/ title: Overview - - path: /engine/api/get-started/ - title: Get started - path: /engine/api/sdk/ title: SDKs + - path: /engine/api/sdk/examples/ + title: SDK examples - path: /engine/api/latest/ title: v{{ site.latest_engine_api_version }} reference (latest) - sectiontitle: API reference by version diff --git a/engine/api/index.md b/engine/api/index.md index 1bd2462ed9..cbc23dc141 100644 --- a/engine/api/index.md +++ b/engine/api/index.md @@ -236,8 +236,7 @@ hello world -For more examples, take a look at the -[Get started guide](/get-started.md). +For more examples, take a look at the [SDK examples](/engine/api/sdk/examples.md). ## Unofficial libraries diff --git a/engine/api/get-started.md b/engine/api/sdk/examples.md similarity index 100% rename from engine/api/get-started.md rename to engine/api/sdk/examples.md diff --git a/engine/api/sdk/index.md b/engine/api/sdk/index.md index 78ecd08d0c..573ddbd641 100644 --- a/engine/api/sdk/index.md +++ b/engine/api/sdk/index.md @@ -260,8 +260,7 @@ hello world -For more examples, take a look at the -[Get started guide](/engine/api/get-started.md). +For more examples, take a look at the [SDK examples](/engine/api/sdk/examples.md). ## Unofficial libraries From c4309a1ef7a2fa1c8ac5a847fe655acb330587cb Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:44:06 +0100 Subject: [PATCH 4/9] Remove duplicated SDK content from API overview Signed-off-by: Sebastiaan van Stijn --- engine/api/index.md | 145 -------------------------------------------- 1 file changed, 145 deletions(-) diff --git a/engine/api/index.md b/engine/api/index.md index cbc23dc141..09ecdcdbc7 100644 --- a/engine/api/index.md +++ b/engine/api/index.md @@ -123,148 +123,3 @@ Docker does not recommend running versions prior to 1.12, which means you are encouraged to use an API version of 1.24 or higher. {% include api-version-matrix.md %} - -## SDK and API quickstart - -Use the following guidelines to choose the SDK or API version to use in your -code: - -- If you're starting a new project, use the - [latest version](/engine/api/latest/), but do specify the version you are - using. This helps prevent surprises. -- If you need a new feature, update your code to use at least the minimum version - that supports the feature, and prefer the latest version you can use. -- Otherwise, continue to use the version that your code is already using. - -As an example, the `docker run` command can be easily implemented using the -Docker API directly, or using the Python or Go SDK. - - -
- -
- -```go -package main - -import ( - "context" - "io" - "os" - - "github.com/docker/docker/api/types" - "github.com/docker/docker/api/types/container" - "github.com/docker/docker/client" - "github.com/docker/docker/pkg/stdcopy" -) - -func main() { - ctx := context.Background() - cli, err := client.NewClientWithOpts(client.FromEnv) - if err != nil { - panic(err) - } - cli.NegotiateAPIVersion(ctx) - - reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) - if err != nil { - panic(err) - } - io.Copy(os.Stdout, reader) - - resp, err := cli.ContainerCreate(ctx, &container.Config{ - Image: "alpine", - Cmd: []string{"echo", "hello world"}, - }, nil, nil, "") - if err != nil { - panic(err) - } - - if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { - panic(err) - } - - statusCh, errCh := cli.ContainerWait(ctx, resp.ID, container.WaitConditionNotRunning) - select { - case err := <-errCh: - if err != nil { - panic(err) - } - case <-statusCh: - } - - out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true}) - if err != nil { - panic(err) - } - - stdcopy.StdCopy(os.Stdout, os.Stderr, out) -} -``` - -
-
- -```python -import docker -client = docker.from_env() -print client.containers.run("alpine", ["echo", "hello", "world"]) -``` - -
-
- -```bash -$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \ - -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \ - -X POST http:/v1.24/containers/create -{"Id":"1c6594faf5","Warnings":null} - -$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start - -$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait -{"StatusCode":0} - -$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1" -hello world -``` - -
-
- -For more examples, take a look at the [SDK examples](/engine/api/sdk/examples.md). - -## Unofficial libraries - -There are a number of community supported libraries available for other -languages. They have not been tested by Docker, so if you run into any issues, -file them with the library maintainers. - -| Language | Library | -|:----------------------|:----------------------------------------------------------------------------| -| C | [libdocker](https://github.com/danielsuo/libdocker) | -| C# | [Docker.DotNet](https://github.com/ahmetalpbalkan/Docker.DotNet) | -| C++ | [lasote/docker_client](https://github.com/lasote/docker_client) | -| Dart | [bwu_docker](https://github.com/bwu-dart/bwu_docker) | -| Erlang | [erldocker](https://github.com/proger/erldocker) | -| Gradle | [gradle-docker-plugin](https://github.com/gesellix/gradle-docker-plugin) | -| Groovy | [docker-client](https://github.com/gesellix/docker-client) | -| Haskell | [docker-hs](https://github.com/denibertovic/docker-hs) | -| HTML (Web Components) | [docker-elements](https://github.com/kapalhq/docker-elements) | -| Java | [docker-client](https://github.com/spotify/docker-client) | -| Java | [docker-java](https://github.com/docker-java/docker-java) | -| Java | [docker-java-api](https://github.com/amihaiemil/docker-java-api) | -| NodeJS | [dockerode](https://github.com/apocas/dockerode) | -| NodeJS | [harbor-master](https://github.com/arhea/harbor-master) | -| Perl | [Eixo::Docker](https://github.com/alambike/eixo-docker) | -| PHP | [Docker-PHP](https://github.com/docker-php/docker-php) | -| Ruby | [docker-api](https://github.com/swipely/docker-api) | -| Rust | [docker-rust](https://github.com/abh1nav/docker-rust) | -| Rust | [shiplift](https://github.com/softprops/shiplift) | -| Scala | [tugboat](https://github.com/softprops/tugboat) | -| Scala | [reactive-docker](https://github.com/almoehi/reactive-docker) | -| Swift | [docker-client-swift](https://github.com/valeriomazzeo/docker-client-swift) | From d021c47d268bf7e3dcf5a9c248fc860b00e8336b Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:45:40 +0100 Subject: [PATCH 5/9] Remove duplicated API reference from SDK docs Signed-off-by: Sebastiaan van Stijn --- engine/api/sdk/index.md | 97 +---------------------------------------- 1 file changed, 2 insertions(+), 95 deletions(-) diff --git a/engine/api/sdk/index.md b/engine/api/sdk/index.md index 573ddbd641..b2d64dd8e4 100644 --- a/engine/api/sdk/index.md +++ b/engine/api/sdk/index.md @@ -52,101 +52,8 @@ or [choose a specific version](/engine/api/version-history/). ## Versioned API and SDK The version of the Docker Engine API you should use depends upon the version of -your Docker daemon and Docker client. - -A given version of the Docker Engine SDK supports a specific version of the -Docker Engine API, as well as all earlier versions. If breaking changes occur, -they are documented prominently. - -> Daemon and client API mismatches -> -> The Docker daemon and client do not necessarily need to be the same version -> at all times. However, keep the following in mind. -> -> - If the daemon is newer than the client, the client does not know about new -> features or deprecated API endpoints in the daemon. -> -> - If the client is newer than the daemon, the client can request API -> endpoints that the daemon does not know about. - -A new version of the API is released when new features are added. The Docker API -is backward-compatible, so you do not need to update code that uses the API -unless you need to take advantage of new features. - -To see the highest version of the API your Docker daemon and client support, use -`docker version`: - -```bash -$ docker version - -Client: - Version: 19.03.5 - API version: 1.40 - Go version: go1.12.12 - Git commit: 633a0ea - Built: Wed Nov 13 07:22:37 2019 - OS/Arch: windows/amd64 - Experimental: true - - -Server: - Version: 19.03.5 - API version: 1.40 (minimum version 1.12) - Go version: go1.12.12 - Git commit: 633a0ea - Built: Wed Nov 13 07:29:19 2019 - OS/Arch: linux/amd64 - ... -``` - -You can specify the API version to use, in one of the following ways: - -- When using the SDK, use the latest version you can, but at least the version - that incorporates the API version with the features you need. - -- When using `curl` directly, specify the version as the first part of the URL. - For instance, if the endpoint is `/containers/`, you can use - `/v1.40/containers/`. - -- To force the Docker CLI or the Docker Engine SDKs to use an old version - version of the API than the version reported by `docker version`, set the - environment variable `DOCKER_API_VERSION` to the correct version. This works - on Linux, Windows, or macOS clients. - - ```bash - DOCKER_API_VERSION='1.40' - ``` - - While the environment variable is set, that version of the API is used, even - if the Docker daemon supports a newer version. - -- For the SDKs, you can also specify the API version programmatically, as a - parameter to the `client` object. See the - [Go constructor](https://github.com/moby/moby/blob/master/client/client.go#L136){: target="_blank" class="_"} - or the - [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html). - -### Docker Engine - Enterprise and Docker Engine - Community API mismatch - -If you use Docker Engine - Enterprise in production, we recommend using Docker Engine - Enterprise in development -too. If you can't, such as when your developers use Docker Desktop for Mac or Docker Desktop for -Windows and manually build and push images, then your developers need to configure -their Docker clients to use the same version of the API reported by their Docker -daemon. This prevents the developer from using a feature that is not yet supported -on the daemon where the workload runs in production. You can do this one of two ways: - -- Configure the Docker client to connect to an external daemon running Docker EE. - You can use the `-H` flag on the `docker` command or set the `DOCKER_HOST` - environment variable. The client uses the daemon's latest supported API version. -- Configure the Docker client to use a specific API by setting the `DOCKER_API_VERSION` - environment variable to the API version to use, such as `1.30`. - -### API version matrix - -Docker does not recommend running versions prior to 1.12, which means you -are encouraged to use an API version of 1.24 or higher. - -{% include api-version-matrix.md %} +your Docker daemon and Docker client. Refer to the [versioned API and SDK](/engine/api/#versioned-api-and-sdk) +section in the API documentation for details. ## SDK and API quickstart From 9774d43d657f8e987c6cf14acfae2b232c0b1803 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:46:44 +0100 Subject: [PATCH 6/9] SDK: remove reference to obsolete Go version Signed-off-by: Sebastiaan van Stijn --- engine/api/sdk/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/engine/api/sdk/index.md b/engine/api/sdk/index.md index b2d64dd8e4..bb8afca192 100644 --- a/engine/api/sdk/index.md +++ b/engine/api/sdk/index.md @@ -25,8 +25,9 @@ installed and coexist together. ```bash go get github.com/docker/docker/client ``` + The client requires a recent version of Go. Run `go version` and ensure that you -are running at least version 1.9.4 of Go +are running a currently supported version of Go [Read the full Docker Engine Go SDK reference](https://godoc.org/github.com/docker/docker/client). From c7c1a59dab1cd1511433007bf9035d3e21f28c0b Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:53:54 +0100 Subject: [PATCH 7/9] API docs: recommend using version negotiation Signed-off-by: Sebastiaan van Stijn --- engine/api/index.md | 13 ++++++++----- engine/api/sdk/index.md | 9 ++++----- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/engine/api/index.md b/engine/api/index.md index 09ecdcdbc7..9866666bd8 100644 --- a/engine/api/index.md +++ b/engine/api/index.md @@ -94,11 +94,17 @@ You can specify the API version to use, in one of the following ways: ``` While the environment variable is set, that version of the API is used, even - if the Docker daemon supports a newer version. + if the Docker daemon supports a newer version. This environment variable + disables API version negotiation, and as such should only be used if you must + use a specific version of the API, or for debugging purposes. + +- The Docker Go SDK allows you to enable API version negotiation, automatically + selects an API version that is supported by both the client, and the Docker Engine + that is used. - For the SDKs, you can also specify the API version programmatically, as a parameter to the `client` object. See the - [Go constructor](https://github.com/moby/moby/blob/master/client/client.go#L136){: target="_blank" class="_"} + [Go constructor](https://github.com/moby/moby/blob/v19.03.6/client/client.go#L119){: target="_blank" class="_"} or the [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html). @@ -119,7 +125,4 @@ on the daemon where the workload runs in production. You can do this one of two ### API version matrix -Docker does not recommend running versions prior to 1.12, which means you -are encouraged to use an API version of 1.24 or higher. - {% include api-version-matrix.md %} diff --git a/engine/api/sdk/index.md b/engine/api/sdk/index.md index bb8afca192..ecec20f5ba 100644 --- a/engine/api/sdk/index.md +++ b/engine/api/sdk/index.md @@ -61,9 +61,9 @@ section in the API documentation for details. Use the following guidelines to choose the SDK or API version to use in your code: -- If you're starting a new project, use the - [latest version](/engine/api/latest/), but do specify the version you are - using. This helps prevent surprises. +- If you're starting a new project, use the [latest version](/engine/api/latest/), + but use API version negotiation or specify the version you are using. This + helps prevent surprises. - If you need a new feature, update your code to use at least the minimum version that supports the feature, and prefer the latest version you can use. - Otherwise, continue to use the version that your code is already using. @@ -96,11 +96,10 @@ import ( func main() { ctx := context.Background() - cli, err := client.NewClientWithOpts(client.FromEnv) + cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation()) if err != nil { panic(err) } - cli.NegotiateAPIVersion(ctx) reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) if err != nil { From 3a223f799c5b5d51f767ac375938702b4d28b36d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 16:59:32 +0100 Subject: [PATCH 8/9] SDK: fix some minor issues in go examples Signed-off-by: Sebastiaan van Stijn --- engine/api/sdk/examples.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/engine/api/sdk/examples.md b/engine/api/sdk/examples.md index 0dcbaaabfb..8d6d1b19a1 100644 --- a/engine/api/sdk/examples.md +++ b/engine/api/sdk/examples.md @@ -11,7 +11,7 @@ redirect_from: After you [install Docker](/install/index.md), you can -[install the Go and Python SDKs](/develop/sdk/index.md#install-the-sdks) and +[install the Go or Python SDK](/engine/api/sdk/index.md#install-the-sdks) and also try out the Docker Engine API. Each of these examples show how to perform a given Docker operation using the Go @@ -40,13 +40,14 @@ command prompt: package main import ( - "os" + "context" "io" + "os" + "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/container" - "github.com/docker/docker/pkg/stdcopy" "github.com/docker/docker/client" - "golang.org/x/net/context" + "github.com/docker/docker/pkg/stdcopy" ) func main() { @@ -144,6 +145,7 @@ You can also run containers in the background, the equivalent of typing package main import ( + "context" "fmt" "io" "os" @@ -151,7 +153,6 @@ import ( "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/container" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -230,11 +231,11 @@ You can use the API to list containers that are running, just like using package main import ( + "context" "fmt" "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -306,11 +307,11 @@ This example stops all running containers. package main import ( + "context" "fmt" "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -386,12 +387,12 @@ to change the hard-coded ID of the container to print the logs for. package main import ( + "context" "io" "os" "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -456,11 +457,11 @@ List the images on your Engine, similar to `docker image ls`: package main import ( + "context" "fmt" "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -526,12 +527,12 @@ Pull an image, like `docker pull`: package main import ( + "context" "io" "os" "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -600,6 +601,7 @@ Pull an image, like `docker pull`, with authentication: package main import ( + "context" "encoding/base64" "encoding/json" "io" @@ -607,7 +609,6 @@ import ( "github.com/docker/docker/api/types" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { @@ -699,12 +700,12 @@ Commit a container to create an image from its contents: package main import ( + "context" "fmt" "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/container" "github.com/docker/docker/client" - "golang.org/x/net/context" ) func main() { From 16d565cae63cf290d0b0b71f078da6af486d4119 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 24 Feb 2020 17:00:52 +0100 Subject: [PATCH 9/9] API remove section about enterprise API version mismatch Signed-off-by: Sebastiaan van Stijn --- engine/api/index.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/engine/api/index.md b/engine/api/index.md index 9866666bd8..e91faa0a2d 100644 --- a/engine/api/index.md +++ b/engine/api/index.md @@ -108,21 +108,6 @@ You can specify the API version to use, in one of the following ways: or the [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html). -### Docker Engine - Enterprise and Docker Engine - Community API mismatch - -If you use Docker Engine - Enterprise in production, we recommend using Docker Engine - Enterprise in development -too. If you can't, such as when your developers use Docker Desktop for Mac or Docker Desktop for -Windows and manually build and push images, then your developers need to configure -their Docker clients to use the same version of the API reported by their Docker -daemon. This prevents the developer from using a feature that is not yet supported -on the daemon where the workload runs in production. You can do this one of two ways: - -- Configure the Docker client to connect to an external daemon running Docker EE. - You can use the `-H` flag on the `docker` command or set the `DOCKER_HOST` - environment variable. The client uses the daemon's latest supported API version. -- Configure the Docker client to use a specific API by setting the `DOCKER_API_VERSION` - environment variable to the API version to use, such as `1.30`. - ### API version matrix {% include api-version-matrix.md %}