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

  • autoreload: restart the server when file changes, default False

  • conf: 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, parent=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.


Configure a logger’s formatter to use the format defined in this web setting.

get_app(settings=False, handlers=None)[source]

Return the tornado.web.Application defined by this settings. This is primarily how an HTTP server interacts with this class. Additional settings and handlers accepted as parameters.


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

static load_class(kls)[source]

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

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, parent=None, **kwargs)[source]

BiothingWebSettings subclass with functions specific to an elasticsearch backend.

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.

async read_index_mappings(biothing_type=None)[source]

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.







Elasticsearch Query Builder

Elasticsearch Query

Elasticsearch Result Transformer