API using REST

We have created an API using REST with a partial implementation of this website functionality.

The REST API can be accessed in this url: https://www.cancergenomeinterpreter.org/api/v1

To be able to use this feature you need to register in our website and request an authentication token as well as accept our terms of use.

Info! If you have issues with the certificate you can perform connexions without verifing the ceriticate using the --insecure flag in curl or the parameter verify=False in the Python requests.

Launching a job

To be able to launch a job, do a POST to https://www.cancergenomeinterpreter.org/api/v1 providing your email and token:

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
payload = {'cancer_type': 'CANCER TYPE', 'title': 'Title of the run', 'reference': 'hg38 or hg19'}
r = requests.post('https://www.cancergenomeinterpreter.org/api/v1',
                headers=headers,
                files={
                        'mutations': open('/paht/to/your/mutations.ext', 'rb'),
                        'cnas': open('/paht/to/another/file.ext', 'rb'),
                        'translocations': open('/paht/to/yet/another/file.ext', 'rb')
                        },
                data=payload)
r.json()

                    
curl --request POST \
  --url https://www.cancergenomeinterpreter.org/api/v1 \
  --header 'Authorization: example@email.com your_token' \
  -F "mutations=@/paht/to/your/file.ext" \
  -F "cnas=@/paht/to/another/file.ext" \
  -F "translocations=@/paht/to/yst/another/file.ext" \
  -F "cancer_type=CANCER TYPE" \
  -F "reference=hg19 \
  -F "title=Title of the run"

The possible parameters for a job are:

cancer_type: cancer type under analysis. This parameter is required and must be one of the values between brackets that you can find in the analysis page.
title: title for this run. This paremter is optional
cnas: file containing the CNA data. Find information about the formats in the FAQs page.
mutations: file containing the mutation data. Find information about the formats in the FAQs page.
translocations: file containing the translocation data. Find information about the formats in the FAQs page.

Note: the files (cnas, mutations and traslocations) are optional, but at least one is required.

Getting the identifiers

To get a list with the identifiers of your jobs do a GET to https://www.cancergenomeinterpreter.org/api/v1

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
r = requests.get('https://www.cancergenomeinterpreter.org/api/v1', headers=headers)
r.json()

                    
curl --request GET \
  --url https://www.cancergenomeinterpreter.org/api/v1 \
  --header 'Authorization: example@email.com your_token'

Accessing a job information

To get the basic information from a job https://www.cancergenomeinterpreter.org/api/v1/job_id

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
r = requests.get('https://www.cancergenomeinterpreter.org/api/v1/job_id', headers=headers)
r.json()

                    
curl --request GET \
  --url https://www.cancergenomeinterpreter.org/api/v1/job_id \
  --header 'Authorization: example@email.com your_token'

Actions on a job

In addition to getting the basic job information, there are a few other operations you can perform on the job data and its results. The different actions are:

download: download the job results
logs: get the logs of the job execution. It can be useful to access this information while the job is executing

To perform any of those operations, you only need to make a get indicating the action to be performed https://www.cancergenomeinterpreter.org/api/v1/job_id?action=action_to_be_performed

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
payload={'action':'logs'}
r = requests.get('https://www.cancergenomeinterpreter.org/api/v1/job_id', headers=headers, params=payload)
r.json()

                    
curl --request GET \
  --url https://www.cancergenomeinterpreter.org/api/v1/job_id \
  --header 'Authorization: example@email.com your_token' \
  -G --data 'action=logs'

When downloading the results, it is likely that you want to store the results file. The extension of such a file is: zip

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
payload={'action':'download'}
r = requests.get('https://www.cancergenomeinterpreter.org/api/v1/job_id', headers=headers, params=payload)
with open('file.zip', 'wb') as fd:
    fd.write(r._content)

                    
curl --request GET \
  --url https://www.cancergenomeinterpreter.org/api/v1/job_id \
  --header 'Authorization: example@email.com your_token' \
  -G --data 'action=download' \
  -o file.zip

Deleting a job

To be able to delete a job, do a DELETE to https://www.cancergenomeinterpreter.org/api/v1 providing the job identifier your email and token:

Python
Curl

                    
import requests
headers = {'Authorization': 'example@email.com your_token'}
r = requests.delete('https://www.cancergenomeinterpreter.org/api/v1/job_id', headers=headers)
r.json()

                    
curl --request DELETE \
  --url https://www.cancergenomeinterpreter.org/api/v1/jobid \
  --header 'Authorization: example@email.com your_token'

The token in needed in any communication between the end user and the REST API.

Only registered users can request a token.