RFC basic user API

[tiborsimko]

The purpose of this issue is to discuss basic REANA API from the end-user
perspective. We'll concentrate on the analysis API. There will be more later
such as resource API etc. So here, we are touching only how to start an
analysis, submit input data, run and monitor the workflow, and obtain the
results back.

Here are tentative sequence diagrams for illustration:

1. Prepare new analysis

CLIENT ----> SERVER --------------------------> CLOUD

client ----> POST /api/:tenant/analyses    ---> create new analysis of :uuid in DB
                                                create workspace on the shared filesystem
                                                (e.g. /reana/analyses/:uuid/workspace/)
       <---- 201 CREATED :uuid

2. Seed analysis workspace

CLIENT ------------> SERVER -----------------------------------------> CLOUD

         push files
client ------------> POST /api/:tenant/analyses/:uuid/workspace   ---> add posted files to :workspace
       <----------- 201 CREATED list of input files

3. Enquire about analysis execution status

CLIENT -----------------> SERVER ------------------------------------> CLOUD

        get information
client -----------------> GET /api/:tenant/analyses/:uuid/status  ---> check status
       <---------------- 200 OK :status (waiting, running, stopped, paused, finished)

4. Manage analysis execution

CLIENT -----------------> SERVER -----------------------------------> CLOUD

        start, stop, pause
client -----------------> PUT /api/:tenant/analyses/:uuid/status ---> run, stop, pause when you can (after a step)
       <---------------- 200 OK :status requested

5. List results

CLIENT -----------------> SERVER ---------------------------------------> CLOUD

        get information
client -----------------> GET /api/:tenant/analyses/:uuid/workspace  ---> list available output files in the workspace
       <---------------- 200 OK list of filenames

6. Grab results

CLIENT -----------------> SERVER ---------------------------------------> CLOUD

        get file content
client -----------------> GET /api/:tenant/analyses/:uuid/workspace/:filename  ---> grab content of output filename
       <---------------- 200 OK content blob

7. Grab logs

CLIENT -----------------> SERVER ---------------------------------> CLOUD

client -----------------> GET /api/:tenant/analyses/:uuid/log  ---> grab content of stdout/stderr of analyses
       <---------------- 200 OK content                                (with pod ids, timestamps)

8. Delete analysis

CLIENT -----------------> SERVER -------------------------------> CLOUD

            delete
client -----------------> DELETE /api/:tenant/analyses/:uuid ---> clean workspace
       <---------------- 204  No content

The above serves to start discussion. Its content may be updated as we go along.

[lukasheinrich]

for log grabbing, we should add endpoints to get logs for the individual jobs of the workflow.

[diegodelemos]

Implementation has diverged (as it can be seen in REANA server API docs) since there was no agreement. This RFC can be reopened in the future if needed, closing for now.