API access

[haraldschilly]

This issue is for brainstorming about a small API for SMC projects. One use case, similar to #19, is a way to automatically upload files into a certain directory. A way to implement this could be this:

1. in the project settings, generate one or more API access token - that's a password-like hash, which can be revoked at any time. If there is a need to specify certain permissions, they are tied to such a token. Each HTTP request has to specify in its HTTP header this access token: x-smc-authorization: <token>.
2. expose RESTful service URLs like: https://SMC/projects/<ID>/api/<verb> where verb is the kind of action you want to do. Besides the <verb>, also the type of request is important.

Verbs / Type:

• files / POST or PUT:
  • Additional Headers:
    • x-smc-filename: the filename (mandatory; is there a standard for POST file uploads to include the filename?)
    • x-smc-path: the path, where the file is stored. (optional, if not specified, its $HOME). If the path doesn't exist, create it.
• files / PATCH: this is similar to POST or PUT, except that the transferred content is a classical diff file to patch the target file. This might come in handy, if you have a larger csv file and just want to append new results to it.
  • Additional Headers: see above
  • The reply should contain an information if the patch has been applied cleanly; we also have to figure out what to do if it doesn't work.
• files / GET: almost identical to the raw file view, except that it uses the authorization token to download the file and hence bypasses the cookie based authentication. GET requests on directories (and especially on / ... which is $HOME) might list all the files in that directory.
• files / DELETE: this would also exist as a regular http request. the main question is, if delete requests should be handled at all - probably there is no need anyways.
• cmd / POST: execute a command. The headers should contain the path where it should run (default is $HOME) and another header is the exact command line that should be executed. Questions are, should it wait for completion or run asynchronously with a timeout? x-smc-async: (true|false) could set this ... but makes this even more complicated.

Replies:

• send a bit of JSON encoded information. e.g. {status: "ok"} or {status: "error", error: "error message"}

[williamstein]

The ID would be stored in the database, as a new field for projects, rather than stored in the project itself. This would make it possible to carry out some actions without even starting the project -- e.g., uploading a file can be done directly. Ideas for other verbs? How dangerous should we get?

- (re-)start project server
- execute a line of code (in the terminal)
- ??

[haraldschilly]

I can start thinking about some. About uploading, the path and the filename should be part of the header in the POST request, that's more natural for RESTful services.

[haraldschilly]

added clarifications about files for PUT, POST, GET and PATCH. also a sketchy idea about running a command.

[williamstein]

Christopher Trudeau (a UW undergrad who works at a company that does API's) is working on this as part of his final project for my Sage course.

[rudimk]

Hey, Dr. Stein, Harald. So just wondering - what's the latest on the API? I was writing a mobile app to demo at Droidcon India, using our cloud platform for math, and I really wanted to write a mobile app that hooks into SMC, and demo that as well.

[williamstein]

Unfortunately, there is no current progress or work on a public API right now...

[haraldschilly]

@rudimk have you looked into https://github.com/sagemath/android ?

[rudimk]

Ah, okay. Well, now I remember I'd seen the Android app in the repo, but I'd totally forgotten about it. I was thinking more of a mobile app that allows you to hook up with SMC, create projects, start Sage worksheets, that sort of thing. But this Android app is definitely something I should check out. Thanks!

[pdehaye]

Any update here?

[williamstein]

We have not done any work on an API due to being focused on not dying. Is this something you might use in Switzerland? What functionality would you need?

On Thursday, September 10, 2015, pdehaye [email protected] wrote:

Any update here?

— Reply to this email directly or view it on GitHub https://github.com/sagemath/cloud/issues/60#issuecomment-139272909.

Sent from my massive iPhone 6 plus.

[pdehaye]

Of course, I understand. I am trying to shoehorn my existing workflow to what SageMathCloud can currently do, not asking you to develop new stuff. For possible reference later, this is what I did in previous years:

• equivalent of a SMC assignment gets distributed to students
• students work on it in groups
• I collect the assignments
• I hand it back, not only to original students but to others as well (i.e. show the project to other students)
• we all comment on it (well, me, and I hope students read it and a few participate in the discussion)

I can try piecing the existing tools together to approach that workflow. If I have a more precise idea later of what is missing I will let you know.

[williamstein]

On Thursday, September 10, 2015, pdehaye [email protected] wrote:

Of course, I understand. I am trying to shoehorn my existing workflow to what SageMathCloud can currently do, not asking you to develop new stuff. For possible reference later, this is what I did in previous years:

• equivalent of a SMC assignment gets distributed to students
• students work on it in groups
• I collect the assignments
• I hand it back, not only to original students but to others as well (i.e. show the project to other students)
• we all comment on it (well, me, and I hope students read it and a few participate in the discussion) I can try piecing the existing tools together to approach that workflow. If I have a more precise idea later of what is missing I will let you know.

It would be fairly easy for me to add something like this to the course management functionality. Let me think about it. Also if you can make things even more precise that would be helpful. Could you make a new ticket about this?

— Reply to this email directly or view it on GitHub https://github.com/sagemath/cloud/issues/60#issuecomment-139278559.

Sent from my massive iPhone 6 plus.

[pdehaye]

Will try to think it through, so as not to make anyone waste time.