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
|
## Versioned API and SDK
|
||||||
|
|
||||||
The version of the Docker Engine API you should use depends upon the version of
|
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: 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
|
## SDK and API quickstart
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue