Islandviewer 4 - Genomic Island Prediction and Genome Visualization Tool

HTTP API

IslandViewer 4 comes with an HTTP API to enable the batch submission of genomes and the retrieval of genomic island predictions using any or the combination of tools integrated in IslandViewer 4.

Available functions

The API currently enables to:

Query the availability of reference and precomputed genomes
Submit custom genomes (draft or complete) to IslandViewer 4
Retrieve information about already submitted genomes - only for authenticated users
Query the status of submitted genomes
Download the Genbank including genomic island predictions, and the reordered concatenated contigs for draft genomes
Download the table summarizing genomic island predictions
Query the reference genomes used for IslandPick predictions by comparative genomics, query possible genomes to use for IslandPick predictions using standard or custom cutoffs for distance, and resubmit an IslandPick analysis.

How does it work?

The HTTP API can be used as an anonymous user or an authenticated user. To use the API as an anonymous user, simply use an empty authentication token. To use the API as an authenticated user, please log in first (currently available authentication possibilities are Github or Google) and then click on the JOBS menu to find your unique HTTP API authentication token. Users can submit genomes and retrieve results using various programming language such as cURL, python or perl (see below for examples). After a successful genome submission, the interface returns a unique job token that can be used to retrieve all information about the status of the submission as well as prediction results. Please note that using the API as an anonymous user requires to carefully store the job token to be able to access the GI results when they become available. Using the API as an authenticated user further enables to retrieve all information, including the required job token, about all genomes previously submitted by the same user.

During a first evaluation period of the HTTP API usage, genome submissions using the API are limited to rates of 2/minute, 30/hour, and 200/day and per user for both authenticated and anonymous users. Requests using the API are limited to 10/minute and 120/hour per user. These rates will be adapted based on user experience and as we further improve the service. Please contact us if you encounter major problems with rate limitations.

To visualize results of a genome submitted using the HTTP API in IslandViewer interactive web interface, please modify the following url with the correct job token: https://www.pathogenomics.sfu.ca/islandviewer/results/job_token.

Please note that API authentication tokens are only valid for a certain time. You can find the expiry date and request a new authentication token if necessary in the menu JOBS - HTTP API Token.

cURL examples

We provide here examples of the syntax to use the various HTTP API functionalities of IslandViewer 4 using cURL, a command line tool for getting or sending files using URL syntax. Please place your authentication token where indicated and replace the job token by the appropriate value.

- Query the availability of reference and precomputed genomes

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/genomes/ -H 'x-authtoken:your_authentication_token'

- Submission of custom genomes (draft or complete) to IslandViewer 4

For complete genomes:

curl -X POST -H 'x-authtoken:your_authentication_token' -Fgenome_file=@tiny.gbk -Fgenome_name="my genome" -Femail_addr="me@email.addr.com" -Fformat_type="GENBANK" https://www.pathogenomics.sfu.ca/islandviewer/rest/submit/

For draft genomes, please provide the accession number of the desired reference genome for contig reordering with the option -Fref_accnum. To obtain a list of available reference genomes, please see above.

curl -X POST -H 'x-authtoken:your_authentication_token' -Fref_accnum="NC_022792.1" -Fgenome_file=@tiny.gbk -Fgenome_name="my test" -Femail_addr="me@email.addr.com" -Fformat_type="GENBANK" https://www.pathogenomics.sfu.ca/islandviewer/rest/submit/

- Retrieve information about already submitted genomes - only for authenticated users

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/jobs/ -H 'X-authtoken:your_authentication_token'

- Query the status of already submitted genomes

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/ -H 'X-authtoken:your_authentication_token'

- Download the Genbank including genomic island predictions, and the reordered concatenated contigs for draft genomes

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/download/genbank/ -H 'x-authtoken:your_authentication_token'

- Download the table summarizing genomic island predictions

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/download/tab/ -H 'x-authtoken:your_authentication_token'

- Query possible genomes to use in IslandPick comparative genomics predictions comparison using standard or custom cutoffs for distance, and resubmit an IslandPick analysis. Please note that, as the number of reference genomes grows, choosing very broad distance cutoffs might results in too many genomes to be returned.

curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/islandpick/ -H 'x-authtoken:your_authentication_token'


curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/islandpick/picker/ -H 'x-authtoken:your_authentication_token'


curl "https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/islandpick/picker/?min_cutoff=0.02&max_dist_single_cutoff=0.15&max_cutoff=0.21&min_compare_cutoff=3&max_compare_cutoff=6&min_gi_size=4000" -H 'x-authtoken:your_authentication_token'


curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/islandpick/picker/ -H 'x-authtoken:your_authentication_token' -X POST -d '{ "min_cutoff": 0.02, "max_dist_single_cutoff": 0.15, "max_cutoff": 0.21 }'


curl https://www.pathogenomics.sfu.ca/islandviewer/rest/job/job_token/islandpick/rerun/ -H 'x-authtoken:your_authentication_token' -X POST -d '{ "genomes": ["NZ_CP008896.1", "NZ_CP012400.1", "NZ_CP011317.1"], "min_gi_size": 8000 }'

Perl script example

We provide here an example of perl script to submit a genome to IslandViewer 4. Please place your authentication token where indicated. Further functions can be built by changing the code to reflect the syntax provided above in cURL examples.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
 
use HTTP::Request::Common;
use LWP::UserAgent;
use CGI qw(:standard);
use strict;
use warnings;
 
my ($file, $result, $message);
 
$file = "tiny.gbk";
 
my $ua = LWP::UserAgent->new;
my $req = $ua->request(POST 'https://www.pathogenomics.sfu.ca/islandviewer/rest/submit/',
          (Content_Type => 'form-data',
	   'x-authtoken' => 'your_authentication_token' ),
          Content => [
        email_addr => 'my@email.address.com',
        format_type => "GENBANK",
        genome_name => "my sample genome",
        genome_file => ["$file"],
#  For incomplete genomes include a reference accession
#        ref_accnum => "NC_022792.1"
          ]
);
 
print "\nRESPONSE -- \n" . $req->as_string;
 
# Check the outcome of the response
if ($req->is_success) {
    print $req->content;
}
else {
  print "\n in else not success\n";
}

Python script example

We provide here an example of python script to submit a genome to IslandViewer 4. Please place your authentication token where indicated, and add the correct genome file in place of "mygenome.gbk". To build further functions, please change the code to reflect the syntax provided above in cURL examples.

import requests, sys
from requests_toolbelt.multipart.encoder import MultipartEncoder

 
server = "https://www.pathogenomics.sfu.ca/islandviewer"
ext = "/rest/submit/"

mygenome="mygenome.gbk"

multipart_data = MultipartEncoder(
    fields={ "format_type": "GENBANK",
             'email_addr': 'my@email.address.com',
#  For incomplete genomes include a reference accession
#             'ref_accnum': 'NC_022792.1',
             'genome_file': ('filename', open(mygenome, 'rb'), 'text/plain')}
)
headers={'Content-Type': multipart_data.content_type,
         'x-authtoken': 'your_authentication_token'}

r = requests.post(server+ext, headers=headers, data=multipart_data)
 
if not r.ok:
  r.raise_for_status()
  sys.exit()
 
decoded = r.json()
print repr(decoded)