diff --git a/_data/toc.yaml b/_data/toc.yaml index a185eb5f5b..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/sdks/ + - 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 new file mode 100644 index 0000000000..e91faa0a2d --- /dev/null +++ b/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 %} diff --git a/develop/sdk/examples.md b/engine/api/sdk/examples.md similarity index 98% rename from develop/sdk/examples.md rename to engine/api/sdk/examples.md index f572545c59..8d6d1b19a1 100644 --- a/develop/sdk/examples.md +++ b/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() { diff --git a/develop/sdk/index.md b/engine/api/sdk/index.md similarity index 61% rename from develop/sdk/index.md rename to engine/api/sdk/index.md index b3446e6397..ecec20f5ba 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 @@ -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 -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 +## 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'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. -## 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 -For more examples, take a look at the -[getting started guide](examples.md). +For more examples, take a look at the [SDK examples](/engine/api/sdk/examples.md). ## Unofficial libraries