What you see is what you REST - how to use it

[lungben]

I just played around with @ctrekker REST API #1052

How to get it running:

Pluto Server:

julia> ]
pkg> activate --temp
pkg> add https://github.com/ctrekker/Pluto.jl#wysiwyr2
julia> import Pluto; Pluto.run(enable_rest=true)

Then open / create a notebook which should be the REST server and keep it running (in this example, "rest_test.jl").

Julia client using new Pluto functions:

]
pkg> activate --temp
pkg> add https://github.com/ctrekker/Pluto.jl#wysiwyr2
using Pluto
nb = PlutoNotebook("rest_test.jl") # notebook name without path
nb.a # get a global variable value
nb(; a=8).y # get a variable value calculated after changing another variable
myfunc = nb.myfunc # gets handle to call a remote function
myfunc(42) # returns function result

This works fine for me.

As next step, I tried to use the API with standard HTTP requests (this is especially important if the clients are not using Julia):

julia> ]
pkg> activate --temp
pkg> add HTTP
using HTTP
r = HTTP.get("localhost:1234/1/rest_test.jl/eval/a")

However, this has not worked for me. Probably I got the request URL wrong, but I could not figure it out what is the correct one.

A 3rd use case would be to call the REST API of one notebook from within another notebook.
I tried in a 2nd notebook

nb = PlutoNotebook("rest_test.jl")

But this did not work for me (UndefVarError: PlutoNotebook not defined).

Could you please help me with the last 2 use cases?

In general the REST API feature is great and I am really looking forward for its release!

[ctrekker]

I'm so glad you tried it out, this feedback is very helpful for me! I'm glad the first case works as expected, I have a few notes regarding the 2nd and 3rd.

For interacting with a standard HTTP request the requirements are rather specific, which is why I'm currently working on writing some more detailed documentation for the HTTP API itself. I've uploaded the notebook in it's unfinished state here. It currently contains information about how serialization works and the form eval requests must take.

2nd Scenario - Manual HTTP Requests

For example, the following example will use the HTTP API to update a and retrieve the resulting value of y.

import MsgPack
using HTTP

headers = [
    "Content-Type" => "application/x-msgpack",
    "Accept" => "application/x-msgpack"
]
body = Dict(
    :inputs => Dict(
        :a => 8
    ),
    :outputs => [:y]
)
r = HTTP.post("http://localhost:1234/v1/notebook/rest_test.jl/eval", headers, MsgPack.pack(body))
@show MsgPack.unpack(r.body)

Regarding the headers:

• Content-Type will tell the API what serialization format you are sending your body in
• Accept will tell the API what serialization format you would like to receive your body in

3rd Scenario - From other Pluto notebooks

This currently works if you insert a using Pluto cell somewhere. However after seeing your issue I think that the PlutoNotebook structure should probably be included in Pluto notebooks by default, similarly to @bind. One of the problems I have with this is that it would add HTTP inside every notebook (from inside PlutoRunner). I'm sure there's a way around this, such as loading HTTP dynamically with eval if a REST function is called. Any thoughts?

I really appreciate the feedback as it helps me tremendously in figuring out which parts of the interface and API still need work, so thanks again!

[lungben]

Thanks, I'll try this out!

For 3) putting the REST access functionality into a separate package may help (see my comment to your PR). Then you can specifically import this package in your notebook when you want to access other notebooks from it. Furthermore, this package would be useful for querying from non-Pluto Julia scripts.

[lungben]

Re 2 - I can make a Python version of PlutoRESTClient when the API is stable.

One application I can think of is using a workflow management tool like https://www.prefect.io/ which make calls to the Pluto REST API for specific processing steps.

[lungben]

Thanks, I tested scenario 2) and it works correctly.

[ctrekker]

Re 2 - I can make a Python version of PlutoRESTClient when the API is stable.

That would be great! I don't have any experience with publishing Python packages but a while ago I did make significant progress on a Python version of the client: https://gist.github.com/ctrekker/13cec7a798b1dc58125f404bc9f32f17. I haven't tested it lately but it should still work, I just haven't looked into how to properly package it

[lungben]

Packaging in Python is unfortunately a bit more complicated than in Julia. A tutorial is given here: https://packaging.python.org/tutorials/packaging-projects/
I have not done this myself yet, neither, but would be happy to help.

[lungben]

For illustrating the cross-language capabilities: with the following code you can access the Pluto REST API from Python (based on @ctrekker 's answer for Julia above):

import requests
import msgpack

headers = {"Content-Type": "application/x-msgpack", "Accept": "application/x-msgpack"}
body = {"inputs": {'a': 8}, "outputs": ['y']}
r = requests.post(url="http://localhost:1234/v1/notebook/rest_test.jl/eval", headers=headers, data=msgpack.packb(body))
msgpack.unpackb(r.content)