biothings.web.handlers¶
biothings.web.handlers.base¶
Biothings Web Handlers
biothings.web.handlers.BaseHandler
Supports: - access to biothings namespace - monitor exceptions with Sentry
biothings.web.handlers.BaseAPIHandler
Additionally supports: - JSON and YAML payload in the request body - request arguments standardization - multi-type output (json, yaml, html, msgpack) - standardized error response (exception -> error template) - analytics and usage tracking (Google Analytics and AWS) - default common http headers (CORS and Cache Control)
- class biothings.web.handlers.base.BaseAPIHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseHandler
,AnalyticsMixin
- cache = None¶
- cache_control_template = 'max-age={cache}, public'¶
- format = 'json'¶
- get_template_path()[source]¶
Override to customize template path for each handler.
By default, we use the
template_path
application setting. Return None to load templates relative to the calling file.
- kwargs = {'*': {'format': {'default': 'json', 'enum': ('json', 'yaml', 'html', 'msgpack'), 'type': <class 'str'>}}}¶
- name = '__base__'¶
- prepare()[source]¶
Called at the beginning of a request before get/post/etc.
Override this method to perform common initialization regardless of the request method.
Asynchronous support: Use
async def
or decorate this method with .gen.coroutine to make it asynchronous. If this method returns anAwaitable
execution will not proceed until theAwaitable
is done.New in version 3.1: Asynchronous support.
- set_default_headers()[source]¶
Override this to set HTTP headers at the beginning of the request.
For example, this is the place to set a custom
Server
header. Note that setting such headers in the normal flow of request processing may not do what you want, since headers may be reset during error handling.
- write(chunk)[source]¶
Writes the given chunk to the output buffer.
To write the output to the network, use the flush() method below.
If the given chunk is a dictionary, we write it as JSON and set the Content-Type of the response to be
application/json
. (if you want to send JSON as a differentContent-Type
, callset_header
after callingwrite()
).Note that lists are not converted to JSON because of a potential cross-site security vulnerability. All JSON output should be wrapped in a dictionary. More details at http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ and https://github.com/facebook/tornado/issues/1009
- write_error(status_code, **kwargs)[source]¶
from tornado.web import Finish, HTTPError
raise HTTPError(404) raise HTTPError(404, reason=”document not found”) raise HTTPError(404, None, {“id”: “-1”}, reason=”document not found”) -> {
“code”: 404, “success”: False, “error”: “document not found” “id”: “-1”
}
biothings.web.handlers.query¶
Elasticsearch Handlers
biothings.web.handlers.BaseESRequestHandler
Supports: (all features above and) - access to biothing_type attribute - access to ES query pipeline stages - pretty print elasticsearch exceptions - common control option out_format
Subclasses: - biothings.web.handlers.MetadataSourceHandler - biothings.web.handlers.MetadataFieldHandler - myvariant.web.beacon.BeaconHandler
biothings.web.handlers.ESRequestHandler
Supports: (all features above and) - common control options (raw, rawquery) - common transform options (dotfield, always_list…) - query pipeline customization hooks - single query through GET - multiple quers through POST
Subclasses: - biothings.web.handlers.BiothingHandler - biothings.web.handlers.QueryHandler
- class biothings.web.handlers.query.BaseQueryHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseAPIHandler
- prepare()[source]¶
Called at the beginning of a request before get/post/etc.
Override this method to perform common initialization regardless of the request method.
Asynchronous support: Use
async def
or decorate this method with .gen.coroutine to make it asynchronous. If this method returns anAwaitable
execution will not proceed until theAwaitable
is done.New in version 3.1: Asynchronous support.
- write(chunk)[source]¶
Writes the given chunk to the output buffer.
To write the output to the network, use the flush() method below.
If the given chunk is a dictionary, we write it as JSON and set the Content-Type of the response to be
application/json
. (if you want to send JSON as a differentContent-Type
, callset_header
after callingwrite()
).Note that lists are not converted to JSON because of a potential cross-site security vulnerability. All JSON output should be wrapped in a dictionary. More details at http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ and https://github.com/facebook/tornado/issues/1009
- class biothings.web.handlers.query.BiothingHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseQueryHandler
Biothings Annotation Endpoint
URL pattern examples:
/{pre}/{ver}/{typ}/? /{pre}/{ver}/{typ}/([^/]+)/?
queries a term against a pre-determined field that represents the id of a document, like _id and dbsnp.rsid
GET -> {…} or [{…}, …] POST -> [{…}, …]
- name = 'annotation'¶
- class biothings.web.handlers.query.MetadataFieldHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseQueryHandler
GET /metadata/fields
- kwargs = {'*': {'format': {'default': 'json', 'enum': ('json', 'yaml', 'html', 'msgpack'), 'type': <class 'str'>}}, 'GET': {'prefix': {'default': None, 'type': <class 'str'>}, 'raw': {'default': False, 'type': <class 'bool'>}, 'search': {'default': None, 'type': <class 'str'>}}}¶
- name = 'fields'¶
- class biothings.web.handlers.query.MetadataSourceHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseQueryHandler
GET /metadata
- kwargs = {'*': {'format': {'default': 'json', 'enum': ('json', 'yaml', 'html', 'msgpack'), 'type': <class 'str'>}}, 'GET': {'dev': {'default': False, 'type': <class 'bool'>}, 'raw': {'default': False, 'type': <class 'bool'>}}}¶
- name = 'metadata'¶
- class biothings.web.handlers.query.QueryHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseQueryHandler
Biothings Query Endpoint
URL pattern examples:
/{pre}/{ver}/{typ}/query/? /{pre}/{ver}//query/?
GET -> {…} POST -> [{…}, …]
- name = 'query'¶
biothings.web.handlers.services¶
- class biothings.web.handlers.services.APISpecificationHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseAPIHandler
- class biothings.web.handlers.services.FrontPageHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶
Bases:
BaseHandler