From e60fc9f532bcc6ffac617e639bbca7fefb48db94 Mon Sep 17 00:00:00 2001 From: Teemu Kataja Date: Tue, 2 Apr 2019 13:45:40 +0300 Subject: [PATCH 1/3] docs for #81 --- beacon_api/conf/config.ini | 38 ++++++++++++++--------------- docs/instructions.rst | 50 +++++++++++++++++++++++++++++++++++++- 2 files changed, 68 insertions(+), 20 deletions(-) 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/instructions.rst b/docs/instructions.rst index 149723fa..a474fdcb 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 @@ -216,3 +216,51 @@ For loading data into the database from selected samples only we can proceed as As of this moment we do not provide an option for bulk upload of files from a dataset. .. note:: For loading 1000 genome dataset see: :ref:`genome-dataset` instructions. + +.. _optional-features: + +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 similar to `HATEOAS and HAL`_. It can be used to convey +extra information regarding the beacon service or the dataset response, that resides in a URL that has been constructed ready for use. +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}" + } + ] + } From ef1bdef5eeccf8832bb66f24c784ea458e712e7e Mon Sep 17 00:00:00 2001 From: Stefan Negru Date: Wed, 3 Apr 2019 08:39:41 +0300 Subject: [PATCH 2/3] Apply suggestions from code review Co-Authored-By: teemukataja --- docs/instructions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/instructions.rst b/docs/instructions.rst index a474fdcb..12c74652 100644 --- a/docs/instructions.rst +++ b/docs/instructions.rst @@ -229,10 +229,10 @@ The Beacon specification contains some optional features that may be turned on o Handover Protocol ~~~~~~~~~~~~~~~~~ -The handover protocol is a feature similar to `HATEOAS and HAL`_. It can be used to convey +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, that resides in a URL that has been constructed ready for use. More information about the handover protocol can be read from the `Beacon Project page `_ and -Beacon Specification's `handover issue `_ at github. +Beacon Specification's `handover issue `_ at Github. The handover protocol can be configured in ``config.ini`` as follows: From 7cb841739e218856e8a54ed4066a77018b6051dc Mon Sep 17 00:00:00 2001 From: Teemu Kataja Date: Wed, 3 Apr 2019 09:18:12 +0300 Subject: [PATCH 3/3] move optional features and handover protocol to new page --- docs/index.rst | 1 + docs/instructions.rst | 48 ------------------------------------------- docs/optionals.rst | 45 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 48 deletions(-) create mode 100644 docs/optionals.rst 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 12c74652..2a6c53dc 100644 --- a/docs/instructions.rst +++ b/docs/instructions.rst @@ -216,51 +216,3 @@ For loading data into the database from selected samples only we can proceed as As of this moment we do not provide an option for bulk upload of files from a dataset. .. note:: For loading 1000 genome dataset see: :ref:`genome-dataset` instructions. - -.. _optional-features: - -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, that resides in a URL that has been constructed ready for use. -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}" - } - ] - } 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}" + } + ] + }