diff --git a/beacon_api/conf/config.ini b/beacon_api/conf/config.ini index 9278c72a..7a6effb3 100644 --- a/beacon_api/conf/config.ini +++ b/beacon_api/conf/config.ini @@ -39,25 +39,6 @@ alturl= createtime=2018-07-25T00:00:00Z -[handover_info] -# The base url for all handovers -# if this url is empty or commented, handover feature is disabled -#drs=https://examplebrowser.org - -# Make the handovers 1- or 0-based -handover_base = 1 - -# Handovers for datasets -dataset_paths= - Variants,browse the variants matched by the query,dataset/{dataset}/browser/variant/{chr}-{start}-{ref}-{alt} - Region,browse data of the region matched by the query,dataset/{dataset}/browser/region/{chr}-{start}-{end} - Data,retrieve information of the datasets,dataset/{dataset}/browser - -# Handovers for general beacon -beacon_paths= - Project,retrieve information about the datasets,dataset/{dataset} - - [organisation_info] # Globally unique identifier for organisation that hosts this Beacon service org_id=fi.csc @@ -84,6 +65,25 @@ org_logoUrl=https://www.csc.fi/documents/10180/161914/CSC_2012_LOGO_RGB_72dpi.jp org_info=CSC represents Finland in the ELIXIR partner nodes +[handover_info] +# The base url for all handovers +# if this url is empty or commented, handover feature is disabled +#drs=https://examplebrowser.org + +# Make the handovers 1- or 0-based +handover_base = 1 + +# Handovers for datasets +dataset_paths= + Variants,browse the variants matched by the query,dataset/{dataset}/browser/variant/{chr}-{start}-{ref}-{alt} + Region,browse data of the region matched by the query,dataset/{dataset}/browser/region/{chr}-{start}-{end} + Data,retrieve information of the datasets,dataset/{dataset}/browser + +# Handovers for general beacon +beacon_paths= + Project,retrieve information about the datasets,dataset/{dataset} + + [oauth2] # OAuth2 server that returns public key for JWT Bearer token validation server=https://login.elixir-czech.org/oidc/jwk diff --git a/docs/index.rst b/docs/index.rst index ee304356..94e14ad3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,6 +45,7 @@ Table of Contents Deployment API Examples Handling Permissions + Optional Features Python Modules Testing diff --git a/docs/instructions.rst b/docs/instructions.rst index 149723fa..2a6c53dc 100644 --- a/docs/instructions.rst +++ b/docs/instructions.rst @@ -79,7 +79,7 @@ The configuration variables reside in the same `CONFIG_FILE` as described above .. literalinclude:: /../beacon_api/conf/config.ini :language: python - :lines: 68-76 + :lines: 87-95 ``server`` should point to an API that returns a public key which can be used to validate the received Bearer token. ``issuers`` is a string of comma separated values, e.g. `one,two,three` without spaces. The issuers string contains diff --git a/docs/optionals.rst b/docs/optionals.rst new file mode 100644 index 00000000..0daba1a1 --- /dev/null +++ b/docs/optionals.rst @@ -0,0 +1,45 @@ +Optional Features +================= + +The Beacon specification contains some optional features that may be turned on or off. + +.. _handover-protocol: + +Handover Protocol +----------------- + +The handover protocol is a feature comparable to `HATEOAS and HAL `_. It can be used to convey +extra information regarding the Beacon service, or the dataset response. +More information about the handover protocol can be read from the `Beacon Project page `_ and +Beacon Specification's `handover issue `_ at Github. + +The handover protocol can be configured in ``config.ini`` as follows: + +.. literalinclude:: /../beacon_api/conf/config.ini + :language: python + :lines: 68-84 + +.. note:: Handover protocol is disabled by default, as shown by the commented out ``drs`` variable. This variable should point + to the server, which serves the additional data. To enable the handover protocol, uncomment the ``drs`` variable. + +The handover protocol will generate new objects to the ``beacon`` root object according to information given in the +``beacon_paths`` variable and to the ``includeDatasetResponses`` object according to information in ``dataset_paths``. +The line is spliced, so that the first CSV element becomes the ``label`` key in the handover, the second element becomes +the ``description`` key and the third element becomes the ``url`` key. + +Taking the first line from ``dataset_paths`` as an example, produces an object in the ``includeDatasetResponses`` object as follows: + +.. code-block:: javascript + + { + "datasetHandover": [ + { + "handoverType": { + "id": "CUSTOM", + "label": "Variants" + }, + "description": "browse the variants matched by the query", + "url": "https://examplebrowser.org/dataset/{dataset}/browser/variant/{chr}-{start}-{ref}-{alt}" + } + ] + }