mirror of https://github.com/docker/docs.git
Remove duplicated API reference from SDK docs
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
parent
c4309a1ef7
commit
d021c47d26
|
|
@ -52,101 +52,8 @@ 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 %}
|
||||
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.
|
||||
|
||||
## SDK and API quickstart
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue