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 {