Merge pull request #10332 from usha-mandya/engine-api-patch

Fix Engine API toc

_data/toc.yaml

@@ -957,10 +957,10 @@ reference:
     section:
     - path: /engine/api/
       title: Overview
-    - path: /engine/api/get-started/
+    - path: /engine/api/sdk/
-      title: Get started
-    - path: /engine/api/sdks/
       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

engine/api/index.md

@@ -0,0 +1,113 @@
+---
+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. 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/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).
+
+### API version matrix
+
+{% include api-version-matrix.md %}

engine/api/sdk/examples.md

@@ -3,15 +3,15 @@ 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
 [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() {

engine/api/sdk/index.md

@@ -1,14 +1,10 @@
 ---
-title: Develop with Docker Engine SDKs and API
+title: Develop with Docker Engine SDKs
-description: Using Docker SDKs and APIs to automate Docker tasks in your language of choice
+description: Using Docker SDKs to automate Docker tasks in your language of choice
-keywords: developing, api, sdk
+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
@@ -29,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).
@@ -56,114 +53,21 @@ 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.
+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.
 
-A given version of the Docker Engine SDK supports a specific version of the
+## SDK and API quickstart
-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:      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
-
-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
-```
-
-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.27/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.27'
-  ```
-
-  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 %}
-
-### Choose the SDK or API version to use
 
 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
+- If you're starting a new project, use the [latest version](/engine/api/latest/),
-  [latest version](/engine/api/latest/), but do specify the version you are
+  but use API version negotiation or specify the version you are using. This
-  using. This helps prevent surprises.
+  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.
 
-## 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.
 
@@ -192,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 {
@@ -264,8 +167,7 @@ hello world
   </div>
 </div>
 
-For more examples, take a look at the
+For more examples, take a look at the [SDK examples](/engine/api/sdk/examples.md).
-[getting started guide](examples.md).
 
 ## Unofficial libraries