Proposal: A new user-focused client API

[bfirsh]

It has been suggested that this library should just be a set of low-level types for implementing clients, but I am proposing we expand the remit of engine-api to make it easier to do things like running containers, handling events, pulling containers, and so on.

Here is a sketch of what it could look like: https://github.com/bfirsh/docker-sdk-go

Here is a similar proposal for docker-py: docker/docker-py#1086

Thoughts?

[CooCooCaCha]

What if the api was implemented in Rust so writing wrappers in other languages is easier? The API would then become a library that can be linked to for python, ruby, etc libraries.

[cpuguy83]

@CooCooCaCha You can already do the same thing by compiling the go lib as a shared library. go build -buildmode=c-shared -o

[CooCooCaCha]

@cpuguy83 That is true, however there is a know, significant overhead with using Go shared libraries in other languages because of the translation to GC'd objects.

[bfirsh]

In my sketch, I was trying to design a more object-orientated design, where methods for a container live on a container struct, and so on. I'm starting to think this might just be unnecessary complication/confusion.

Given #379 , I think we have two other options:

1. docker-sdk-go is simply a very thin wrapper around github.com/docker/docker/api/client with extra methods for running, pulling, handling events, etc.
2. We refactor the Docker client a bit so github.com/docker/docker/api/client is the complete Docker client, with reusable methods for running, pulling, handling events, etc.

The neatness of (2) is very tempting. It also means it maintains itself, because it is the canonical implementation. The downside is there's not a great entrypoint for users to discover it. We would need a good set of docs for it on docs.docker.com, and perhaps a readme in github.com/docker/docker/api/client to explain what it is all about.

[dnephin]

I like the idea (2). I think it's worth mentioning that what is currently in api/client is actually the cli commands. I think the package name is not great. We should probably move api/client to cli/client before we move the engine-api client stuff back there.

[stevvooe]

@dnephin Please do. I wish this was a precursor to shutting down engine-api project.

In general, the client available in docker/docker should represent the forward/backwards compatibility horizon of the docker project.

[bfirsh]

Looks like it's github.com/docker/docker/client now.

I'll have a go at writing a run method in a way that both the CLI and other people can use. ContainerRun, or something.