HTTP REST API v1

Authentication

Authentication is based on secret tokens. In order to use the A||GO HTTP API, you need to copy your private token from your profile page. All requests must be include an Authorization header:

Authorization: Token token=<your_private_token>

Post a job

POST /api/v1/jobs

Submit a new job

form job[webapp_id]

int webapp identifier

form job[param]

a string used as parameter

form files[0]

a first file

form files[1]

a second file, etc …

reqheader Authorization

Token token=<your_private_token>

reqheader Content-Type

multipart/form-data

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":40155,
  "url":"https://allgo18.inria.fr/api/v1/jobs/40155"
  "avg_time": 0
}

Here is a example with curl

curl -H 'Authorization: Token token=<your_private_token>' -X POST -F job[webapp_id]=<service_id>
     -F job[param]='' -F files[0]=@<path_to_file0> -F files[1]=@<path_to_file1>
     https://allgo18.inria.fr/api/v1/jobs

This request will return you, either the errors, or if it’s ok, your job_id

Monitor a job

GET /api/v1/jobs/(int: job_id)/events
query offset

optional starting offset (in bytes) for streaming the logs (default is 0). Use -1 to disable the logs.

reqheader Authorization

Token token=<your_private_token>

This endpoint streams a sequence of line-delimited json objects to report the progress of the job.

The current implementation produces four kind of messages:

  • Status: reports the new state of the job

    {"status":  "<NEW_STATUS>"}
    
  • Logs: streams the console output of the job (allgo.log)

    {"logs": "<CONTENT>"}
    

    EOF on the console is signaled with an empty logs message:

    {"logs": ""}
    
  • EOF: sent at the end of the stream

    {"eof": null}
    
  • Keepalive: empty messages sent periodically to ensure that the connection is alive

    {}
    

Notes

  • The API may be extended in the future. Any unknown kind of message should be ignored by the client.

  • The stream ends when the job is terminated and the end of logs is reached. An eof message is sent to mark the end of the stream. If the stream terminates without the eof message, then you should assume that it was prematurely terminated. You may consider making a new request to resume the stream (possibly with a positive offset value to resume the logs where it was interrupted), but please wait at least a few seconds before making the new request (to avoid overloading the server in case your app enters an infinite loop).

  • States changes and logs are streamed independently of each other, therefore you may receive logs even after the job is reported as terminated. Only the eof message guarantees that the stream is terminated.

  • If your need is only to be notified when the job terminates (you are not interested in processing a stream of json object), then you should just make a minimal request (without the logs) GET /api/v1/jobs/<ID>/events?offset=-1 and ignore the content of the response. The request will finish when the job terminates.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "waiting" }
{}
{}
{ "status": "running" }
{ "logs": "some output\n" }
{}
{ "logs": "some other output\n" }
{ "status": "done" }
{ "logs": "end of the output\n" }
( "logs": "" }
{ "eof": null }

Get the results

Get the result of the job and the output files with:

GET /api/v1/jobs/(int: job_id)

Retrieve job informations

reqheader Authorization

Token token=<your_private_token>

Example response:

{
 "40155":
   {"conv1_samusa.txt":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
    "conv1.json":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
    "conv1.mp3":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
    "allgo.log":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
    },
 "status":"done"
 }

Each file could be downloaded with the link associated.

http

GET /api/v1/jobs/40155 HTTP/1.1
Host: allgo18.inria.fr
Accept: application/json
Authorization: Token token=<your_private_token>

curl

curl -i -X GET https://allgo18.inria.fr/api/v1/jobs/40155 -H "Accept: application/json" -H "Authorization: Token token=<your_private_token>"

wget

wget -S -O- https://allgo18.inria.fr/api/v1/jobs/40155 --header="Accept: application/json" --header="Authorization: Token token=<your_private_token>"

httpie

http https://allgo18.inria.fr/api/v1/jobs/40155 Accept:application/json Authorization:"Token token=<your_private_token>"

python-requests

requests.get('https://allgo18.inria.fr/api/v1/jobs/40155', headers={'Accept': 'application/json', 'Authorization': 'Token token=<your_private_token>'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "40155":
   {"conv1_samusa.txt":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
    "conv1.json":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
    "conv1.mp3":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
    "allgo.log":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
    },
 "status":"done"
 }

Get metrics

We provide a way to get simple metrics about your applications. It allows to get for a given webapp, the number of job over a period of time.

GET /api/v1/metrics/(string: metric_type)/(int: webapp_id)

We provide 4 metrics type:

  • per_user : the number of jobs per time period and per user.

  • per_result : the number of jobs per time period and per result.

  • created : the number of jobs created per time period.

  • all : all jobs created per time period.

3 parameters can refine your request :

  • step : string [year,month,week,day], the step of aggregation. By default set to ‘day’

  • from : date, the begin (including) of the time period to interrogate. By default set to ‘first result’

  • to : date, the end (excluding) of the time period to interrogate. By default set to ‘last result’

    Note: the dates should have the format “%Y-%m-%d”, so 2019-04-01 for the first of april 2019.

reqheader Authorization

Token token=<your_private_token>

http

GET /api/v1/metrics/per_user/151?from=2019-01-01&step=day HTTP/1.1
Host: allgo18.inria.fr
Accept: application/json
Authorization: Token token=<your_private_token>

curl

curl -i -X GET 'https://allgo18.inria.fr/api/v1/metrics/per_user/151?from=2019-01-01&step=day' -H "Accept: application/json" -H "Authorization: Token token=<your_private_token>"

wget

wget -S -O- 'https://allgo18.inria.fr/api/v1/metrics/per_user/151?from=2019-01-01&step=day' --header="Accept: application/json" --header="Authorization: Token token=<your_private_token>"

httpie

http 'https://allgo18.inria.fr/api/v1/metrics/per_user/151?from=2019-01-01&step=day' Accept:application/json Authorization:"Token token=<your_private_token>"

python-requests

requests.get('https://allgo18.inria.fr/api/v1/metrics/per_user/151?from=2019-01-01&step=day', headers={'Accept': 'application/json', 'Authorization': 'Token token=<your_private_token>'})

Example response:

{
  "GATB-Compiler": {
    "from": "01-01-2017 00:00",
    "to": "01-01-2018 00:00",
    "data": [
      {
        "time_period": "2017-01-01T00:00:00Z",
        "result": "ERROR",
        "n": 2499
      },
      {
        "time_period": "2017-01-01T00:00:00Z",
        "result": "SUCCESS",
        "n": 22
      },
      ...
    ]
  }
}