docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API docs: recommend using version negotiation 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2020-02-24 16:53:54 +01:00
parent 9774d43d65
commit c7c1a59dab
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 12 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
engine/api/index.md
View File

@ -94,11 +94,17 @@ You can specify the API version to use, in one of the following ways:
``` ```
While the environment variable is set, that version of the API is used, even While the environment variable is set, that version of the API is used, even
if the Docker daemon supports a newer version. 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 - For the SDKs, you can also specify the API version programmatically, as a
parameter to the `client` object. See the parameter to the `client` object. See the
[Go constructor](https://github.com/moby/moby/blob/master/client/client.go#L136){: target="_blank" class="_"} [Go constructor](https://github.com/moby/moby/blob/v19.03.6/client/client.go#L119){: target="_blank" class="_"}
or the or the
[Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html). [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html).
@ -119,7 +125,4 @@ on the daemon where the workload runs in production. You can do this one of two
### API version matrix ### 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 %} {% include api-version-matrix.md %}

9
engine/api/sdk/index.md
View File

@ -61,9 +61,9 @@ section in the API documentation for details.
Use the following guidelines to choose the SDK or API version to use in your Use the following guidelines to choose the SDK or API version to use in your
code: code:
- If you're starting a new project, use the - If you're starting a new project, use the [latest version](/engine/api/latest/),
[latest version](/engine/api/latest/), but do specify the version you are but use API version negotiation or specify the version you are using. This
using. This helps prevent surprises. helps prevent surprises.
- If you need a new feature, update your code to use at least the minimum version - 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. that supports the feature, and prefer the latest version you can use.
- Otherwise, continue to use the version that your code is already using. - Otherwise, continue to use the version that your code is already using.
@ -96,11 +96,10 @@ import (
func main() { func main() {
ctx := context.Background() ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv) cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil { if err != nil {
panic(err) panic(err)
} }
cli.NegotiateAPIVersion(ctx)
reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil { if err != nil {