# Beacon api

A beacon is a gateway to your data. By creating a beacon and pointing at specific data sets within the MOLGENIS database, you allow people to query multiple data sets via one entry point.

Read more about beacons [here](https://beacon-network.org/#/about).

The MOLGENIS Beacons are meant to be used with genetic data sets containing at least the following column types:

* Chromosome
* Start position
* Reference allele(s)
* Alternative allele(s)

A MOLGENIS beacon only exposes whether a specific variant **exists**. Nothing more.

## Organization

An organization can be used to organize one or more beacons. An organization is the business card for your beacons. When hooking up your beacon to the global <https://beacon-network.org>, the organization information is shown when your beacons respond to queries.

## Creating your first beacon

When you have uploaded some genetic data sets in the form of an EMX or VCF, you can go to the Dataexplorer to start creating your first beacon.

The following examples work with [this data](https://github.com/molgenis/molgenis/tree/ed1370930eb06a48caf8d16bf83e00e32e273943/docs/data/beacon_set.vcf).

Select the *Beacon* table in the dropdown, and add a new row.

![Creating a Beacon](https://1452226688-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLUgz0ctDlFMwo2_rIW%2F-M1B5_MLXyQMGRYDh-v-%2F-M1B5eHnpeAomR4RdYBq%2Fadd-beacon-form.png?generation=1582898531125228\&alt=media)

The beacon created here has only one data set, namely *beacon\_set*.\
Note that the Organization is still empty, we will come back to that later.

Now that we have created a beacon, we can actually already query for variants.

**Seeing a list of all the beacons**\
`http://localhost:8080/beacon/list`

*produces*

```javascript
[
 {
   "id": "MyFirstBeacon",
   "name": "My First Beacon",
   "apiVersion": "v0.3.0",
   "datasets": [
     {
       "id": "beacondataset",
       "name": "My First Beacon dataset"
     }
   ]
 }
]
```

**See the info of one beacon**\
`http://localhost:8080/beacon/MyFirstBeacon`

*produces*

```javascript
{
   "id": "MyFirstBeacon",
   "name": "My First Beacon",
   "apiVersion": "v0.3.0",
   "datasets": [
     {
       "id": "beacondataset",
       "name": "My First Beacon dataset"
     }
   ]
}
```

**Query the beacon for a variant via GET or POST**\
`http://localhost:8080/beacon/MyFirstBeacon/query?referenceName=7&start=130148888&referenceBases=A&alternateBases=C`

`http://localhost:8080/beacon/MyFirstBeacon/query`

```javascript
{
  "referenceName": "7",
  "start": 130148888,
  "referenceBases": "A",
  "alternateBases": "C"
}
```

*produces*

```javascript
{
  "beaconId": "MyFirstBeacon",
  "exists": true,
  "alleleRequest": {
    "referenceName": "7",
    "start": 130148888,
    "referenceBases": "A",
    "alternateBases": "C"
  }
}
```

**When querying goes wrong**\
When an exception occurs, we return a response containing a BeaconError

```javascript
{
  "beaconId": "MyFirstBeacon",
  "error": {
    "errorCode": 400,
    "message": "Unknown beacon [MyFirstBeacon]"
  },
  "alleleRequest": {
    "referenceName": "7",
    "start": 130148888,
    "referenceBases": "C",
    "alternateBases": "A"
  }
}
```

## Creating an organization

For your beacon to look nice to the world, we will add it to an organization.

In the dataexplorer, go to the dropdown in the top right, select the *BeaconOrganization* table, and add a new row

![Creating a Beacon Organization](https://1452226688-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLUgz0ctDlFMwo2_rIW%2F-M1B5_MLXyQMGRYDh-v-%2F-M1B5eHfFrc2JRunrBHB%2Fcreate-organization-form.png?generation=1582898531078799\&alt=media)

Configure dataset as Beacon

![Configure dataset as a beacon](https://1452226688-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLUgz0ctDlFMwo2_rIW%2F-M1B5_MLXyQMGRYDh-v-%2F-M1B5eHj7fqUsOQ1VlBC%2Fconfigure-beacon-as-dataset-form.png?generation=1582898530824089\&alt=media)

And now we can link to this organization and dataset by editing the Beacon row we created before

![Adding a Beacon](https://1452226688-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLUgz0ctDlFMwo2_rIW%2F-M1B5_MLXyQMGRYDh-v-%2F-M1B5eHnpeAomR4RdYBq%2Fadd-beacon-form.png?generation=1582898531125228\&alt=media)

And by requesting info on our beacon again\
`http://localhost:8080/beacon/MyFirstBeacon`

We now get information on our organization

```javascript
{
  "id": "MyFirstBeacon",
  "name": "My First Beacon",
  "apiVersion": "v0.3.0",
  "organization": {
    "id": "beaconorg",
    "name": "Beacon organization",
    "description": "Beacon organizational unit"
  },
  "datasets": [
    {
      "id": "beacondataset",
      "name": "My First Beacon dataset"
    }
  ]
}
```

## Specifications

The complete specification can be found on [ga4gh-beacon/specification](https://github.com/ga4gh-beacon/specification)

Within MOLGENIS we decided on a subset of the API. Due to the dynamic nature of our data, we can not always supply all fields.