Skip to content

Latest commit

 

History

History
89 lines (67 loc) · 3.24 KB

beacon-flavours.md

File metadata and controls

89 lines (67 loc) · 3.24 KB
Raw

Beacon "Flavours"

!!! Note "About UI" Most of the information that you will find here is related to the Beacon v2 specification. For that reason, the examples are shown as REST API requests/responses in the form of JSON. If you are only interested in using beacon with a graphical interface please visit the implementations page.

While the original Beacon v1 only provided Boolean (i.e. YES/NO) responses on queries for the existence of specific genomic variants, Beacon v2 is a flexible protocol that supports different usage scenarios - also called "flavours", since they are more a representation of usage types w/o prescribing their specific details.

Importantly, the Beacon framework separates query options from the response side. In that way a privacy-protecting1 Boolean Beacon still may offer more query features - and therefore better usability - compared to the first Beacon concept implementations.

!!! Important "Technical Notes"

For detailed information about the technical implementation of the different logical
scopes please see the [Framework](framework.md) documentation.

Aggregate Response Beacons - Boolean and Count

A Boolean Response Beacon is in it's response similar to Beacon v1 - i.e. responding with a true or false value when queried for the existence of some data in a resource. Similarly a Count Response Beacon only returns aggregate information, i.e. the number of matched entries (e.g. genomic variants), a feature also part of the Beacon v1 protocol.

However, in contrast to earlier versions, in Beacon v2 in principle a beaconized resource may implement all types of query options (e.g. combinations of various filters and genomic query parameters) but still only offer a Boolean and optionally Count response.

Also, all Beacons should implement the Boolean Response format as fallback option and handle extended options depending on the user's authentication status.

=== "Boolean Response in v2"

```json
{
  "meta": {
    "apiVersion": "v2.0.0",
    "__other_meta_parameters__": "..."
    "receivedRequestSummary": {
      "requestedGranularity": "boolean",
      "__other_request_parameters__": "..."
    },
    "returnedGranularity": "boolean"
   },
  "responseSummary": {
    "exists": true
  }
}
```

=== "Count Response in v2"

```json
{
  "meta": {
    "apiVersion": "v2.0.0",
    "__other_meta_parameters__": "..."
    "receivedRequestSummary": {
      "requestedGranularity": "count",
      "__other_request_parameters__": "..."
    },
    "returnedGranularity": "count"
   },
  "responseSummary": {
    "exists": true,
    "numTotalResults": 42
  }
}
```

Beacons Supporting Data and Information Delivery

!!! Important "Technical Notes"

For detailed information about the technical implementation of the different logical
scopes please see the [Models](models.md) documentation.

Information about the different data delivery options can be found here:

Footnotes

  1. Privacy protecting as in "reasonably protecting by design but not immune to complex re-identification attacks". ↩