API Proposal

[yuvipanda]

This needs a versioned, simple RESTful API that allows for a wide variety of use cases.

Some of the use cases it should cater for:

1. Working as an on-demand backend for ipywidgets and related toolkits that want to talk to a kernel
2. mybinder.org like use-cases with various levels of authentication

We should collect other use cases too before finalizing the API design.

Some API design guidelines I like (and should re-read before doing the design):

1. Google's API Design guidelines https://cloud.google.com/apis/design/
2. Heroku's API Design guidelines https://geemus.gitbooks.io/http-api-design/content/en/

[choldgraf]

This is also probably a conversation in which @minrk would have useful perspective

[yuvipanda]

@choldgraf you are looking for #15 :) This one is about a HTTP JSON API, which afaict Binder doesn't have.

[choldgraf]

are we gonna keep this open to discuss new API things? Right now there's just filepath right?

[yuvipanda]

Nope, this is unrelated to that - this is for the API that js clients can use. We don't have a stable one for that yet, so yes we should keep it open.

[yuvipanda]

Ideally, someone who would use the API should describe their use case and tell us what their ideal flow would look like :)

[jasongrout]

Ideally, someone who would use the API should describe their use case and tell us what their ideal flow would look like :)

Well since you asked :).

It'd be nice if we could use it essentially as a kernel spawning service with a specific setup for the kernel. We have an example right now that uses tmpnb to spawn a kernel (see https://github.com/jupyter-widgets/ipywidgets/blob/master/examples/web-tmpnb/src/index.ts), and then send the kernel code to execute. If we could spawn a kernel with a specific configuration (for example, a specific version of ipywidgets installed), that would be great.

[choldgraf]

a number of people (e.g. the Juno folks, @rgbkrk , @minrk ) have worked out ways to connect w/ Binder via the API. As a start on this issue can we document how they did this, so that others might be able to follow in their footsteps?

[rgbkrk]

Looked at thebelab's implementation, realized it was an EventSource with a simple path and then wrote two functions:

• formBinderURL - options in, URL out
• binder - options in, Observable wrapped around an EventSource out

These are both in https://github.com/nteract/nteract/blob/master/packages/rx-binder

[minrk]

And we have a Python example in this repo.