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

Wiki

Clone wiki

enterobase-web / api_structure

View History

Top level links:

Understanding the EnteroBase API Structure

The API tends to follow the logical structure for MLST and NGS data in general. e.g. Strains > Traces > Assemblies, and Loci > Alleles > Sequence types (STs).

There are generic query methods such as Lookup and Info that will help with straightforward lookups of information. If you have any suggestions for new endpoints to help your work, please let us know.

Picture1.png

The Swagger sandbox

Swagger is an API framework used in the EnteroBase API. It provides interactive documentation of the EnteroBase API, including information about endpoints, inputs, outputs and response codes.

Link to Enterobase's interactive API documentation (swagger-ui): http://enterobase.warwick.ac.uk/api/v2.0/swagger-ui

Screenshot 2017-02-21 19.45.54.png

You can just right into playing with requests. There is a demo token already embedded, which is only valid for the Salmonella database ('senterica').

Understanding Barcodes

Almost all data in EnteroBase is assigned a unique Barcode. This is a unique identifier across all of EnteroBase. It follows a very straightforward structure, split by underscores:

#!html
SAL_AA0019AA_ST
  • The first part (e.g. SAL) defines the database
  • The middle encodes an ID number, letters are used to allow more information per character similar to a UK postcode (CV4 7AL).
  • The last part defines the datatype (e.g. ST is Sequence Type record).

Databases are encoded:

Genus Tag
Salmonella SAL
Escherichia ESC
Yersinia YER
Moraxella MOR

Datatypes are encoded:

Datatype Barcode tag
Schemes SC
Loci LO
Alleles AL
Assemblies AS
STs ST
Traces TR
Strains None or SS

Rapid Barcode lookup

Some barcodes can be quickly looked up using the Lookup endpoint in the API. A request is as simple as : 

#!html

http://enterobase.warwick.ac.uk/api/v2.0/lookup?barcode=SAL_AA0019AA_ST

This gives you a full information on the record, which in this case is about Sequence Type 19 (Salmonella Typhimurium).

#!json

{
  "records": 1,
  "results": [
    {
      "ST_id": 19,
      "accepted": 1,
      "alleles": [
        {
          "accepted": 1,
          "allele_id": 10,
          "allele_name": null,
          "locus": "aroC"
        },
        {
          "accepted": 1,
          "allele_id": 7,
          "allele_name": null,
          "locus": "dnaN"
        },
        {
          "accepted": 1,
          "allele_id": 12,
          "allele_name": null,
          "locus": "hemD"
        },
        {
          "accepted": 1,
          "allele_id": 9,
          "allele_name": null,
          "locus": "hisD"
        },
        {
          "accepted": 1,
          "allele_id": 5,
          "allele_name": null,
          "locus": "purE"
        },
        {
          "accepted": 1,
          "allele_id": 9,
          "allele_name": null,
          "locus": "sucA"
        },
        {
          "accepted": 1,
          "allele_id": 2,
          "allele_name": null,
          "locus": "thrA"
        }
      ],
      "barcode": "SAL_AA0019AA_ST",
      "create_time": "2015-11-24 19:59:36.295460",
      "index_id": 19,
      "info": {
        "lineage": "",
        "predict": {
          "serotype": [
            [
              "Typhimurium",
              7372
            ],
            [
              "Typhimurium Var. 5-",
              440
            ],
            [
              "Typhimurium Var. O:5-",
              208
            ]
        },
        "st_complex": "1",
        "subspecies": ""
      },
      "lastmodified": "2017-02-19 01:44:21.503891",
      "lastmodified_by": "admin",
      "reference": {
        "lab_contact": "DVI",
        "refstrain": "9924828",
        "source": "mlst.warwick.ac.uk"
      },
      "scheme": "UoW",
      "scheme_index": 1,
      "version": 4885
    }
  ]
}

You can play around with this feature in the interactive documentation

Screenshot 2017-02-21 21.08.02.png

Navigating the API

There is a top-level API page which can be used to find the direct links to the various endpoints for a given database. The interactive documentation is derived from the API itself and is always up-to-date.

You can use either resource if you are lost. 

#!html

http://enterobase.warwick.ac.uk/api/v2.0

#!json

[
  {
    "description": "Salmonella",
    "links": {
      "assemblies": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/assemblies",
      "current": "http://enterobase.warwick.ac.uk/api/v2.0",
      "schemes": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/schemes",
      "straindata": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata",
      "strains": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/strains",
      "sts": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/rMLST/sts",
      "traces": "http://enterobase.warwick.ac.uk/api/v2.0/senterica/traces"
    },
    "name": "senterica",
    "prefix": "SAL",
    "tables": "{'schemes': 'SC', 'snps': 'SN', 'alleles': 'AL', 'assemblies': 'AS', 'loci': 'LO', 'taxondef': 'TA', 'strains': 'SS', 'datadefs': 'DE', 'sts': 'ST', 'traces': 'TR', 'archive': 'AR', 'refsets': 'RE'}"
  }
]

Updated