search

docker / engine-api

DEPRECATED: Please see https://github.com/docker/docker/tree/master/client
Apache License 2.0
264 stars 163 forks source link

Proposal: A new user-focused client API #358

Open bfirsh opened 8 years ago

bfirsh commented 8 years ago

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: https://github.com/docker/docker-py/issues/1086

Thoughts?

CooCooCaCha commented 8 years ago

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 commented 8 years ago

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

CooCooCaCha commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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.