1. Enterobase Avatar Enterobase
  2. enterobase-code
  3. enterobase-web

Wiki

Clone wiki

enterobase-web / Getting started with Enterobase API

View History

Top level links:

Getting started with Enterobase API

All API activity needs to requested through HTTP Basic Authentication and authenticated with a valid token. You must have an account on the EnteroBase website to get your Token.

If you have API access to a database

Your API token should be displayed under 'Important information' in the main database dashboard. (To access a database dashboard, from the main page of http://enterobase.warwick.ac.uk, click 'Database Home')

api_ley.png

If you DO NOT have API access to a database

  1. Make sure you have an account at http://enterobase.warwick.ac.uk
  2. Email us at enterobase@warwick.ac.uk with a message something like:
#!html

Hi EnteroBase administrator , 

I am [YOUR NAME] at [YOUR ORGANISATION] 
and I would like access to the EnteroBase Database 
[DATABASE OF INTEREST; Salmonella, E. coli, Yersinia, Moraxella]. 

I would like to use the API to [YOUR INTENDED PURPOSE]

My username/Email on Enterobase is [YOUR ENTEROBASE USERNAME OR EMAIL YOU USED]

Thanks


[YOUR NAME]

I will get back to you promptly about your request.

Testing out your Token

Once you have your Token you can start using it in scripts to download data from EnteroBase. Here is a simple example that just picks out one assembled strain record using curl:

#!bash

curl --header "Accept: application/json" --user "<YOUR_TOKEN_HERE>:" "https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?sortorder=asc&assembly_status=Assembled&limit=1"

You can build requests like this into Python, with a simple example of the same request below:

#!python
from urllib2 import HTTPError
import urllib2
import base64
import json

API_TOKEN = 'YOUR_TOKEN_HERE'

def __create_request(request_str):

    request = urllib2.Request(request_str)
    base64string = base64.encodestring('%s:%s' % (API_TOKEN,'')).replace('\n', '')
    request.add_header("Authorization", "Basic %s" % base64string)
    return request

address = 'https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?assembly_status=Assembled&limit=1'

try:
    response = urllib2.urlopen(__create_request(address))
    data = json.load(response)
    print json.dumps(data, sort_keys=True, indent=4, separators=(',', ': '))

except HTTPError as Response_error:
    print '%d %s. <%s>\n Reason: %s' %(Response_error.code,
                                                      Response_error.msg,
                                                      Response_error.geturl(),
                                                      Response_error.read())

The main important steps to remember are:

  1. Send your request, usually a GET, with the token added to authorization (Basic) header.
  2. Data will usually come back in JSON so use a module to cast it to a dictionary.

This is the kind of result you get back. It is usually in JSON, which can be easily treated like a dictionary. Most responses are structured like this:

  • links
    • paging; links to the previous/next page of data, like webpage pagination.
    • Number of records on this page (total_records).
    • Total number of records (total_records).
  • data, labelled after the endpoint you've fetched, in this case 'straindata'.
    • (Data for this record...)
#!json

{
    "links": {
        "paging": {
            "next": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?limit=1&assembly_status=Assembled"
        },
        "records": 1,
        "total_records": 367716
    },
    "straindata": {
        "SAL_FA6876AA": {
            "assembly_barcode": "SAL_LA1140AA_AS",
            "assembly_status": "Assembled",
            "city": null,
            "collection_date": 18,
            "collection_month": 5,
            "collection_time": null,
            "collection_year": 2016,
            "comment": null,
            "continent": "Oceania",
            "country": "Australia",
            "county": null,
            "created": "2016-05-18T09:00:04.867617+00:00",
            "download_fasta_link": "http://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_LA1140AA_AS&database=senterica",
            "email": null,
            "lab_contact": "Vitali Sintchenko",
            "lastmodified": "2016-09-06T22:55:53.045179+00:00",
            "latitude": null,
            "longitude": null,
            "n50": 442480,
            "orderby": "barcode",
            "postcode": null,
            "region": "New South Wales",
            "secondary_sample_accession": null,
            "serotype": "Enteritidis",
            "source_details": "NSW ERL",
            "source_niche": "Human",
            "source_type": "Laboratory",
            "strain_barcode": "SAL_FA6876AA",
            "strain_name": "NSW29-074",
            "top_species": "Salmonella enterica;100.0%",
            "uberstrain": "SAL_FA6876AA",
            "version": 1
        }
    }
}

More sample scripts are available at: https://bitbucket.org/enterobase/enterobase-scripts/

Updated