API docs: recommend using version negotiation

Signed-off-by: Sebastiaan van Stijn <[email protected]>

Author: thaJeztah

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 %}

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 {