Python Modules

The beacon_api package contains code to start an EGA Beacon API.


In this file the information about the Beacon is registered. The information is parsed from beacon_api.conf.config.ini

beacon_api.schemas Load JSON Schemas.
beacon_api.api Beacon API endpoints.
beacon_api.permissions Permissions Module.
beacon_api.utils Utilities Module.
beacon_api.conf Beacon Python Application Configuration.
beacon_api.extensions Extensions Module.

API Schemas

Load JSON Schemas.

The JSON schemas represent a good method of checking that an endpoint’s requests/responses adhere to the API specification. Schemas available:

  • info.json - for the /info endpoint response;
  • query.json - for the /query endpoint request;
  • response.json - beacon API JSON response.

Example snippets from query.json:

    "integer": {
      "$id": "$/definitions/integer",
      "type": "integer",
      "minimum": 0
  "required": [
  "properties": {
    "referenceName": {
      "$ref": "#/definitions/chromosome"
    "mateName": {
      "$ref": "#/definitions/chromosome"
    "start": {
      "$ref": "#/definitions/integer"
    "end": {
      "$ref": "#/definitions/integer"
    "startMin": {
      "$ref": "#/definitions/integer"
    "startMax": {
      "$ref": "#/definitions/integer"
      "type": "string",
      "default": "NONE",
      "enum": ["ALL", "HIT", "MISS", "NONE"]
  "dependencies": {
    "end": [
    "startMin": [
    "endMin": [
    "startMax": ["startMin"],
    "endMax": ["endMin"],
    "mateName": {
      "oneOf": [{
        "required": [
        "required": [
        "not": {
          "required": [

Beacon API

Beacon API endpoints.

The endpoints reflect the specification provided by: Endpoints:

  • / - Information about the datasets in the Beacon;
  • /service-info - Information about the Beacon in GA4GH format (extra endpoint);
  • /query - querying/filtering datasets in the Beacon; Info Endpoint.
beacon_api.api.query Query Endpoint.
beacon_api.api.exceptions Custom API exception reponses.

Utility Functions

Utilities Module.

Contains utilities such as database create/load, JSON schema validation, token authentication.

Also contains necessary functions for querying the DB and retrieving and transforming data to desired format.

Other functions include logging formatter.

beacon_api.utils.logging Logging formatting.
beacon_api.utils.db_load Beacon Database Loader.
beacon_api.utils.validate_json JSON Request/Response Validation.
beacon_api.utils.validate_jwt JSON Token authentication.
beacon_api.utils.data_query Query DB and prepare data for response.

Permissions Addons

Permissions Module.

Module for getting permissions to datasets, more precisely CONTROLLED datasets. This module was designed to be addon based, where users of the beacon-python app can write their implementation for parsing a specific JWT token claim that contains CONTROLLED permissions to datasets.

Each file added in this module will consist of a function for parsing a permissions claim from a JWT token. Then this function MUST be added to utils.validate_jwt module in order to pass permissions when retrieving datasets from the database.

To avoid collisions check that your claim for permissions does not conflict with existing ones:

beacon_api.permissions.ga4gh Parse permissions and statuses from ELIXIR token for GA4GH claim.


Beacon Python Application Configuration.

beacon_api.conf.config DB Configuration.


Extensions Module.

This module contains optional extensions to the Beacon Python Server. Currently we have two extensions:

  • handover - used to convey extra information regarding the Beacon service, or the dataset response;
  • mate fusion - used for finding breakend records.
beacon_api.extensions.handover Prepare Handover.
beacon_api.extensions.mate_name Prepare mate.

Index | Module Index