Handover Docs

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

docs/index.rst

@@ -45,6 +45,7 @@ Table of Contents
    Deployment             <deploy>
    API Examples           <example>
    Handling Permissions   <permissions>
+   Optional Features      <optionals>
    Python Modules         <code>
    Testing                <testing>
 

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

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 <https://restfulapi.net/hateoas/>`_. 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 <https://beacon-project.io/roadmap/handover.html>`_ and
+Beacon Specification's `handover issue <https://github.com/ga4gh-beacon/specification/issues/114>`_ 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}"
+            }
+        ]
+    }