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