Problem statement

The API/CLI version compatibility requirement is a pain for a huge number of users, and is only getting worse as we have Docker deployed on more and more heterogeneous environments. On the daemon-side, that logic is implemented in the VersionMiddleware.

        if versions.GreaterThan(apiVersion, v.defaultVersion) {
            return badRequestError{fmt.Errorf("client is newer than server (client API version: %s, server API version: %s)", apiVersion, v.defaultVersion)}
        }
        if versions.LessThan(apiVersion, v.minVersion) {
            return badRequestError{fmt.Errorf("client version %s is too old. Minimum supported API version is %s, please upgrade your client to a newer version", apiVersion, v.minVersion)}
        }

Today, the only possible workaround is a horrific hack that simply overrides the version string using the DOCKER_API_VERSION environment variable.

Possible solution

Create a Go package capable of detecting the remote version and accommodating for that (up to its own capabilities, of course). Perhaps we could create a repository that packages multiple versions of the docker/engine-api project and would be "version-aware"? It would expose the latest Go interface, and could provide policies on ways to deal with unsolvable incompatibilities (e.g., the server you're interacting with doesn't implement feature X).

Any idea is welcome on the best way to tackle this!

Cc @vdemeester @fermayo @crosbymichael.