Sage API

[Robert Bradshaw]

Here is my proposal for a simple Sage API. I started this while at
the AMS joint math meetings this January, but didn't get very far
because I got sidetracked doing the notebook auto-login code.

I would like to share as much code with the notebook as possible. In
this vein, I would propose we use twisted and http. (Twisted will
make it easy to extend to other protocols than http, if we so
desire). An example session is the best way to exemplify what I had
in mind (response is JSON header followed by a body)

http://sageserver/login?username=...&password=...
------------
{
session: 987654321
version: 2.10.3
...
}
-sep-
Welcome to Sage 2.10.3
------------

http://sageserver/compute?session=987654321&code=2*2
------------
{
cell: 1
status: done
files: []
}
-sep-
4
------------

http://sageserver/compute?session=987654321&code=factor(next_prime
(10^50)*next_prime(10^60))
------------
{
cell: 2
status: running
files: []
}
-sep-
------------

http://sageserver/compute?session=987654321&code=factor(next_prime
(10^55)*next_prime(10^65))
------------
{
cell: 3
status: waiting
files: []
}
-sep-
------------

http://sageserver/status?session=987654321&cell=2
------------
{
cell: 2
status: running
files: []
}
-sep-
------------

...time passes...
http://sageserver/status?session=987654321&cell=2
------------
{
cell: 2
status: done
files: []
}
-sep-
100000000000000000000000000000000000000000000000151 *
1000000000000000000000000000000000000000000000000000000000007
------------

http://sageserver/status?session=987654321&cell=3
------------
{
cell: 3
status: running
files: []
}
-sep-
------------

http://sageserver/interrupt?session=987654321

http://sageserver/compute?session=987654321&code=plot(sin(x),
(x,-10,10))\nprint "hi"
------------
{
cell: 4
status: done
files: [sage.png]
}
-sep-
hi
------------

http://sageserver/files?session=987654321&cell=3&file=sage.png
------------
[png data]
------------

http://sageserver/logout?session=987654321
------------
{
/* some stats? */
}
-sep-
Bye.
------------
[all flies/output deleted from the server, unless one wishes to
archive them]

I think this would be relatively easy to write, and easy to use. The
session bears a lot of resemblance to a worksheet as well as
verifying authentication data (and as such should be randomly
generated). If one wants to have to separate sessions one could "log
in" again and get a separately running copy of Sage. If one wants non-
textual representation of objects (e.g. MathML), one instructs Sage
to sage to write to a file, and one can then request that file.

Thoughts?

- Robert

[Carl Witty]

On Feb 22, 6:00 pm, Robert Bradshaw <rober...@math.washington.edu>
wrote:

> Here is my proposal for a simple Sage API. I started this while at
> the AMS joint math meetings this January, but didn't get very far
> because I got sidetracked doing the notebook auto-login code.
>
> I would like to share as much code with the notebook as possible. In
> this vein, I would propose we use twisted and http. (Twisted will
> make it easy to extend to other protocols than http, if we so
> desire). An example session is the best way to exemplify what I had
> in mind (response is JSON header followed by a body)

,,,

> I think this would be relatively easy to write, and easy to use. The
> session bears a lot of resemblance to a worksheet as well as
> verifying authentication data (and as such should be randomly
> generated). If one wants to have to separate sessions one could "log
> in" again and get a separately running copy of Sage. If one wants non-
> textual representation of objects (e.g. MathML), one instructs Sage
> to sage to write to a file, and one can then request that file.
>
> Thoughts?

My first thought is that it had better be "https:" instead of "http:".

Other than that, it looks very usable and useful. I do have a heap of
wishlist items, though. For a little bit of context, let me explain
that my interest in the API comes from the idea of having Java applets
running in the notebook and communicating with Sage to do some sort of
mathematics visualization.

1) It would be nice if such an applet could inherit its login and
session information from its notebook session.

2) It would be nice if such an applet could also run from the command-
line version of Sage (probably by having sage run appletviewer).
(This has almost nothing to do with the API, except that again, we
want the applet to be automatically logged in.)

3) There should be a way to send large amounts of data (that is, you
need to be able to use POST as well as GET).

4) There should be a way to interrupt long-running calculations.

5) There should be a way to block waiting for the result of a
(potentially) long-running calculation (with an optional timeout),
rather than periodically polling. This is more convenient, and also
reduces latency (you can get the result as soon as it's ready, rather
than the next time you happen to poll for it).

Carl

[Robert Bradshaw]

On Feb 22, 2008, at 11:47 PM, Carl Witty wrote:

> On Feb 22, 6:00 pm, Robert Bradshaw <rober...@math.washington.edu>
> wrote:
>> Here is my proposal for a simple Sage API. I started this while at
>> the AMS joint math meetings this January, but didn't get very far
>> because I got sidetracked doing the notebook auto-login code.
>>
>> I would like to share as much code with the notebook as possible. In
>> this vein, I would propose we use twisted and http. (Twisted will
>> make it easy to extend to other protocols than http, if we so
>> desire). An example session is the best way to exemplify what I had
>> in mind (response is JSON header followed by a body)
> ,,,
>> I think this would be relatively easy to write, and easy to use. The
>> session bears a lot of resemblance to a worksheet as well as
>> verifying authentication data (and as such should be randomly
>> generated). If one wants to have to separate sessions one could "log
>> in" again and get a separately running copy of Sage. If one wants
>> non-
>> textual representation of objects (e.g. MathML), one instructs Sage
>> to sage to write to a file, and one can then request that file.
>>
>> Thoughts?
>
> My first thought is that it had better be "https:" instead of "http:".

Of course this should be provided, but I don't think it's a
requirement. I'd imagine much of the time Sage use won't be anything
sensitive, and will often be on the same computer (e.g. someone
offers a web service and the sage process is sitting on the same
computer as the outside-exposed web server). Also, getting applets
+https is much more of a pain than applets+http.

> Other than that, it looks very usable and useful. I do have a heap of
> wishlist items, though.

Thanks for the feedback.

> For a little bit of context, let me explain
> that my interest in the API comes from the idea of having Java applets
> running in the notebook and communicating with Sage to do some sort of
> mathematics visualization.
>
> 1) It would be nice if such an applet could inherit its login and
> session information from its notebook session.

Yep. I'm imagining that login could take several other authentication
parameters other than username/password.

> 2) It would be nice if such an applet could also run from the command-
> line version of Sage (probably by having sage run appletviewer).
> (This has almost nothing to do with the API, except that again, we
> want the applet to be automatically logged in.)

No reason that couldn't be done with the current proposal.

> 3) There should be a way to send large amounts of data (that is, you
> need to be able to use POST as well as GET).

My thoughts too (put POST is harder to demonstrate in an example). I
don't think it should distinguish between POST and GET.

> 4) There should be a way to interrupt long-running calculations.

This was part of my example.

> 5) There should be a way to block waiting for the result of a
> (potentially) long-running calculation (with an optional timeout),
> rather than periodically polling. This is more convenient, and also
> reduces latency (you can get the result as soon as it's ready, rather
> than the next time you happen to poll for it).

This would be good, but I have a hard time imagining how to do it. It
would require the server somehow having the ability to ping the
applet when it was done. But, I would imagine having a timeout
parameter such that when you request a computation/status, it waits
for at least timeout seconds for the task to finish up (returning
immediately if it does). I've noticed some browsers, for instance,
have issues with extremely long-lasting http connections, but it
should in theory be possible to keep the connection open for hours or
more. One could imagine setting timeout=-1 to not return 'till the
task was done.

- Robert

[William Stein]

There is a significant user base for which
exactly this kind of local security does matter a lot.
In pure math research and education it usually isn't an issue, but in
industry, applied math, security research, etc., it can be hugely
important, e.g., since different groups working at the same company
can have access to shared resources, but are not allowed to see
what other groups are working on.

Anyway, please keep security in mind, since basic infrastructure in
Sage that doesn't have a secure alternative shouldn't go into Sage,
in my opinion.

-- William

[Robert Bradshaw]

On Feb 23, 2008, at 10:48 AM, William Stein wrote:

>>> My first thought is that it had better be "https:" instead of
>>> "http:".
>>
>> Of course this should be provided, but I don't think it's a
>> requirement. I'd imagine much of the time Sage use won't be anything
>> sensitive, and will often be on the same computer (e.g. someone
>> offers a web service and the sage process is sitting on the same
>> computer as the outside-exposed web server). Also, getting applets
>> +https is much more of a pain than applets+http.
>
> There is a significant user base for which
> exactly this kind of local security does matter a lot.
> In pure math research and education it usually isn't an issue, but in
> industry, applied math, security research, etc., it can be hugely
> important, e.g., since different groups working at the same company
> can have access to shared resources, but are not allowed to see
> what other groups are working on.
>
> Anyway, please keep security in mind, since basic infrastructure in
> Sage that doesn't have a secure alternative shouldn't go into Sage,
> in my opinion.

I agree 100%. (computer security used to be my job :-). When I said
"not a requirement" I meant that user shouldn't be forced to use
https, but is *is* a requirement that we provide that option.

- Robert

[Robert Bradshaw]

I have implemented my proposal and it is up at http://
trac.sagemath.org/sage_trac/ticket/2346 . It includes working
doctests that demonstrate how to use it.

I am sure there is a lot of room for improvement, but this should be
enough to build a lot of stuff on top of already.

- Robert

On Feb 22, 2008, at 11:47 PM, Carl Witty wrote: