It makes no sense to have the primary arguments for API operations inside of an options structure. It makes the API unwieldy and challenging to use. Let's take the example of Client.ImagePull:

func (cli *Client) ImagePull(ctx context.Context, options types.ImagePullOptions, privilegeFunc RequestPrivilegeFunc) (io.ReadCloser, error)

We then dive into types.ImagePullOptions. Ok, it takes an ImageID. Does that mean name? Who knows. It also requires the user to parse the tag portion out of the name.

Furthermore, the only real option, privilegeFunc is for some reason not an option.

The method signature should be this:

func (cli *Client) ImagePull(ctx context.Context, ref string, options types.ImagePullOptions) (io.ReadCloser, error)

Note a few things about this design. The ref can contain whatever is supported by the target engine. We don't require a user of this API to parse out a tag, which is non-trivial. Futhermore, one can simply pass an empty options structure and 95% of use cases would be covered.

With the options type, as follows:

type ImagePullOptions struct {
    RegistryAuth string // RegistryAuth is the base64 encoded credentials for the registry
    PrivilegesFunc RequestPrivilegesFunc
}

As it is, this is confusing and challenging to use correctly.

I'm not sure if I have time to do a PR for this, as it seems to be a systematic inconsistency.