mirror of https://github.com/docker/docs.git
Merge pull request #10332 from usha-mandya/engine-api-patch
Fix Engine API toc
This commit is contained in:
Sebastiaan van Stijn
GitHub
commit
b7cf4b0888
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
|
|
@ -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() {
|
||||
|
|
@ -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
|
|||
</div>
|
||||
</div>
|
||||
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue