Web component

The BioThings SDK web component contains tools used to generate and customize an API, given an Elasticsearch index with data. The web component uses the Tornado Web Server to respond to incoming API requests.

Server boot script

A simple Biothings API implementation.

  • Process command line arguments to setup the API.

  • Add additional applicaion settings like handlers.

  • port: the port to start the API on, default 8000

  • debug: start the API in debug mode, default False

  • address: the address to start the API on, default

  • profile: choose an alternative setting, default config

  • dir: path to app directory. default: current working directory

index_base.main(app_settings=None, use_curl=False)

Start a Biothings API Server

  • app_handlers – additional web handlers to add to the app

  • app_settings`Tornado application settings dictionary

<http://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings>`_ :param use_curl: Overide the default simple_httpclient with curl_httpclient <https://www.tornadoweb.org/en/stable/httpclient.html>


Config module


class biothings.web.settings.BiothingWebSettings(config=None, **kwargs)[source]

A container for the settings that configure the web API.

  • Environment variables can override settings of the same names.

  • Default values are defined in biothings.web.settings.default.


config – a module that configures this biothing or its fully qualified name, or its module file path.


Generates the tornado.web.Application (regex, handler_class, options) tuples.


Generates settings for tornado.web.Application. This result and the method below can define a tornado application to start a web server.


Return the path of the codebase if the specified folder in settings exists or None.

static load_module(config, default=None)[source]

Ensure config is a module. If config does not evaluate, Return default if it’s provided.


Validate the settings defined for this web server.


class biothings.web.settings.BiothingESWebSettings(config=None, **kwargs)[source]

BiothingWebSettings subclass with functions specific to an elasticsearch backend.

  • Use the known live ES connection if more than one is specified.

  • Cache source metadata stored under the _meta field in es indices.

The config init parameter specifies a module that configures this biothing. For more information see config module documentation.


Return the async elasitcsearch client. The connection is created upon first call. API calls return awaitable objects.


Return the default blocking elasticsearch client. The connection is created upon first call.


Return the cached field notes associated with this instance.

static load_class(kls)[source]

Ensure config is a module. If config does not evaluate, Return default if it’s provided.


Read ES index mappings for the corresponding biothing_type, Populate datasource info and field properties from mappings. Return ES raw response. This implementation combines indices.

The ES response would look like: (for es7+) {

‘index_1’: {

‘properties’: { … }, —> source_properties ‘_meta’: {

“src” : { … } —> source_licenses …

}, ———–> source_metadata …

}, ‘index_2’: {

… ———> Combine with results above




Additional ES settings to validate.




class biothings.web.api.es.handlers.base_handler.BaseESRequestHandler(application, request, **kwargs)[source]

Parent class of all Elasticsearch-based Request handlers, subclass of BaseHandler. Contains handling for Elasticsearch-specific query params (like fields, size, etc)


Request Level initialization.


Extract body and url query parameters into functional groups. Typify predefined user inputs patterns here. Rules:

  • Inputs are combined and then separated into functional catagories.

  • Duplicated query or body arguments will overwrite the previous value.

  • JSON body input will not overwrite query arguments in URL.

  • Path arguments can overwirte all other existing values.

Extend to add more customizations.

write_error(status_code, **kwargs)[source]

Override to implement custom error pages.

write_error may call write, render, set_header, etc to produce output as usual.

If this error was caused by an uncaught exception (including HTTPError), an exc_info triple will be available as kwargs["exc_info"]. Note that this exception may not be the “current” exception for purposes of methods like sys.exc_info() or traceback.format_exc.


class biothings.web.api.es.handlers.biothing_handler.BiothingHandler(application, request, **kwargs)[source]

An Annotation Request

  1. queries a term against a pre-determined field that represents the id of a document, like _id and dbsnp.rsid

  2. should find either exactly 1 or 0 result and returns either 200 for a document found or 404 for not found.

  3. formats the response like the _source field in elasticsearch. Result does not contain _score field, but contains _version.

pre_finish_hook(options, res)[source]

Return single result for GET. Also does not return empty results.

GET /v3/gene/0 {

“success”: false, “error”: “ID ‘0’ not found”



Annotation query has default scopes. Annotation query include _version field. Set GA tracking object.


class biothings.web.api.es.handlers.query_handler.QueryHandler(application, request, **kwargs)[source]

Request handlers for requests to the query endpoint

pre_finish_hook(options, res)[source]



Set GA tracking object.


Perform a quick check to ensure required arguments are present.


Elasticsearch Query Builder

Elasticsearch Query

Elasticsearch Result Transformer