View on GitHub

Xenonflow: Scientific Workflows through a REST API

Xenonflow allows you to run CWL workflows using Xenon on a compute resource through a REST api.

Download this project as a .zip file Download this project as a tar.gz file

Xenon CWL workflow execution service API v1.0.0

This is a reference sheet for all the REST calls that can be made to the Xenonflow server.

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

License: Apache 2.0

Authentication

Jobs API

list of jobs

Code samples


const headers = {
  'Accept':'application/json',
  'api-key':'API_KEY'
};

fetch('/jobs',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /jobs

get a list of all jobs, running, cancelled, or otherwise.

Example responses

200 Response

[
  {
    "id": "afcd1554-9604-11e6-bd3f-080027e8b32a",
    "input": {
      "file1": {
        "class": "File",
        "location": "whale.txt"
      }
    },
    "log": "http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/stderr",
    "name": "myjob1",
    "output": {
      "output": {
        "checksum": "sha1$6f9bd042bff934443cc65f7ef769613222f7b136",
        "basename": "output",
        "location": "file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
        "path": "/tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
        "class": "File",
        "size": 9
      }
    },
    "state": "Success",
    "workflow": "wc-tool.cwl"
  }
]

Responses

Status Meaning Description Schema
200 OK list of jobs Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [job] false none none
» id string(uri) true none none
» name string true none user supplied (non unique) name for this job
» workflow string(uri) true none location of the workflow
» input workflow-binding true none none
» state string true none none
» output workflow-binding true none none
» log string(uri) true none none
» additionalInfo object false none none

Enumerated Values

Property Value
state Waiting
state Running
state Success
state Cancelled
state SystemError
state TemporaryFailure
state PermanentFailure

submit a new job

Code samples

const inputBody = '{
  "name": "myjob1",
  "workflow": "wc-tool.cwl",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'api-key':'API_KEY'
};

fetch('/jobs',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /jobs

Submit a new job from a workflow definition.

Body parameter

{
  "name": "myjob1",
  "workflow": "wc-tool.cwl",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  }
}

Parameters

Name In Type Required Description
body body job-description true Input binding for workflow.
» name body string false user supplied (non unique) name for this job
» workflow body string(uri) true location of the workflow
» input body workflow-binding false none

Example responses

201 Response

{
  "id": "afcd1554-9604-11e6-bd3f-080027e8b32a",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  },
  "log": "http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log",
  "name": "myjob1",
  "output": {},
  "state": "Running",
  "workflow": "wc-tool.cwl"
}

Responses

Status Meaning Description Schema
201 Created OK job

Response Headers

Status Header Type Format Description
201 Location string uri uri of the created job

Get a job

Code samples


const headers = {
  'Accept':'application/json',
  'api-key':'API_KEY'
};

fetch('/jobs/{jobId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /jobs/{jobId}

Parameters

Name In Type Required Description
jobId path string true Job ID

Example responses

200 Response

{
  "id": "afcd1554-9604-11e6-bd3f-080027e8b32a",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  },
  "log": "http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log",
  "name": "myjob1",
  "output": {
    "output": {
      "checksum": "sha1$6f9bd042bff934443cc65f7ef769613222f7b136",
      "basename": "output",
      "location": "file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
      "path": "/tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
      "class": "File",
      "size": 9
    }
  },
  "state": "Success",
  "workflow": "wc-tool.cwl"
}

Responses

Status Meaning Description Schema
200 OK Status of job job
404 Not Found Job not found None

Response Schema

Delete a job

Code samples


const headers = {
  'api-key':'API_KEY'
};

fetch('/jobs/{jobId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /jobs/{jobId}

Delete a job, if job is in waiting or running state then job will be cancelled first.

Parameters

Name In Type Required Description
jobId path string true Job ID

Example responses

Responses

Status Meaning Description Schema
204 No Content Job deleted None
404 Not Found Job not found None

Response Schema

Cancel a job

Code samples


const headers = {
  'Accept':'*/*',
  'api-key':'API_KEY'
};

fetch('/jobs/{jobId}/cancel',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /jobs/{jobId}/cancel

Parameters

Name In Type Required Description
jobId path string true Job ID

Example responses

200 Response

{
  "id": "afcd1554-9604-11e6-bd3f-080027e8b32a",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  },
  "log": "http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log",
  "name": "myjob1",
  "output": {
    "output": {
      "checksum": "sha1$6f9bd042bff934443cc65f7ef769613222f7b136",
      "basename": "output",
      "location": "file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
      "path": "/tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output",
      "class": "File",
      "size": 9
    }
  },
  "state": "Cancelled",
  "workflow": "wc-tool.cwl"
}

Responses

Status Meaning Description Schema
200 OK Job has been cancelled if job was still running or waiting job
404 Not Found Job not found None

Response Schema

Response Headers

Status Header Type Format Description
200 Location string uri uri of the cancelled job

Log of a job

Code samples


const headers = {
  'Accept':'text/plain',
  'api-key':'API_KEY'
};

fetch('/jobs/{jobId}/log',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /jobs/{jobId}/log

Parameters

Name In Type Required Description
jobId path string true Job ID

Example responses

200 Response

"string"

302 Response

"[job wc-tool.cwl] /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a$ wc < /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/stge84d1078-e33f-41c3-8714-aafe955d1b53/whale.txt > /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output\nFinal process status is success\n"

Responses

Status Meaning Description Schema
200 OK Job log string
302 Found Job log redirect None
404 Not Found Job not found None

Response Schema

Response Headers

Status Header Type Format Description
302 Location string uri uri of the log of the job

Get the server status

Code samples


const headers = {
  'Accept':'application/json',
  'api-key':'API_KEY'
};

fetch('/status',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /status

Example responses

200 Response

{
  "waiting": 3,
  "running": 1,
  "successful": 10,
  "errored": 4
}

Responses

Status Meaning Description Schema
200 OK The server status status

A list of available workflows

Code samples


const headers = {
  'Accept':'application/json',
  'api-key':'API_KEY'
};

fetch('/workflows',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /workflows

Example responses

200 Response

[
  {
    "filename": "echo.cwl",
    "path": "cwl/echo.cwl"
  },
  {
    "filename": "my_workflow.cwl",
    "path": "science/my_workflow.cwl"
  }
]

Responses

Status Meaning Description Schema
200 OK The list of available workflows Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [workflow] false none none
» filename string true none none
» path string true none none

Schemas

workflow-binding

{}

Properties

None

job-description

{
  "name": "myjob1",
  "workflow": "wc-tool.cwl",
  "input": {
    "file1": {
      "class": "File",
      "location": "whale.txt"
    }
  }
}

Properties

Name Type Required Restrictions Description
name string false none user supplied (non unique) name for this job
workflow string(uri) true none location of the workflow
input workflow-binding false none none

job

{
  "id": "afcd1554-9604-11e6-bd3f-080027e8b32a",
  "name": "myjob1",
  "workflow": "wc-tool.cwl",
  "input": {},
  "state": "Running",
  "output": {},
  "log": "http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log",
  "additionalInfo": {}
}

Properties

Name Type Required Restrictions Description
id string(uri) true none none
name string true none user supplied (non unique) name for this job
workflow string(uri) true none location of the workflow
input workflow-binding true none none
state string true none none
output workflow-binding true none none
log string(uri) true none none
additionalInfo object false none none

Enumerated Values

Property Value
state Waiting
state Running
state Success
state Cancelled
state SystemError
state TemporaryFailure
state PermanentFailure

file

{
  "id": "input_file",
  "type": "File"
}

Properties

Name Type Required Restrictions Description
id string true none none
type string true none none

workflow

{
  "filename": "echo.cwl",
  "path": "cwl/echo.cwl"
}

Properties

Name Type Required Restrictions Description
filename string true none none
path string true none none

status

{
  "waiting": 2,
  "running": 2,
  "successful": 2,
  "errored": 2
}

Properties

Name Type Required Restrictions Description
waiting integer true none none
running integer true none none
successful integer true none none
errored integer true none none