## Query examples

View query:

- List available beacons
- Show information about a beacon
- List supported genomes
- List supported chromosomes
- List supported alleles
- Query a specific beacon
- Query beacon with a specific genome
- Query all beacons
- Filter reponses for a specific beacon
- Aggregate responses of all beacons via beacon of beacons

### List beacons

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/beacons

Response:

    [
        {
            "aggregator": false,
            "id": "thousandgenomes",
            "name": "1000 Genomes Project",
            "organization": "Google"
        },
        {
            "aggregator": false,
            "id": "thousandgenomes-phase3",
            "name": "1000 Genomes Project - Phase 3",
            "organization": "Google"
        },
        {
            "aggregator": false,
            "id": "amplab",
            "name": "AMPLab",
            "organization": "APMLab"
        },
        {
            "aggregator": true,
            "id": "bob",
            "name": "Beacon Network",
            "organization": "Global Alliance for Genomics and Health"
        },
        {
            "aggregator": false,
            "id": "cafe-cardiokit",
            "name": "Cafe CardioKit",
            "organization": "University of Leicester"
        },
        {
            "aggregator": true,
            "id": "cafe-variome",
            "name": "Cafe Variome",
            "organization": "University of Leicester"
        },
        {
            "aggregator": false,
            "id": "cafe-central",
            "name": "Cafe Variome Central",
            "organization": "University of Leicester"
        },
        {
            "aggregator": false,
            "id": "clinvar",
            "name": "ClinVar",
            "organization": "UCSC"
        },
        {
            "aggregator": false,
            "id": "ebi",
            "name": "EMBL-EBI",
            "organization": "EBI"
        },
        {
            "aggregator": false,
            "id": "curoverse-ref",
            "name": "GA4GH Example Data",
            "organization": "Curoverse"
        },
        {
            "aggregator": true,
            "id": "google",
            "name": "Google Genomics Public Data",
            "organization": "Google"
        },
        {
            "aggregator": false,
            "id": "platinum",
            "name": "Illumina Platinum Genomes",
            "organization": "Google"
        },
        {
            "aggregator": false,
            "id": "kaviar",
            "name": "Known VARiants",
            "organization": "Institute for Systems Biology"
        },
        {
            "aggregator": false,
            "id": "lovd",
            "name": "Leiden Open Variation",
            "organization": "UCSC"
        },
        {
            "aggregator": false,
            "id": "ncbi",
            "name": "NCBI",
            "organization": "NCBI"
        },
        {
            "aggregator": false,
            "id": "curoverse",
            "name": "PGP",
            "organization": "Curoverse"
        },
        {
            "aggregator": false,
            "id": "uniprot",
            "name": "UniProt",
            "organization": "UCSC"
        },
        {
            "aggregator": false,
            "id": "wtsi",
            "name": "Wellcome Trust Sanger Institute",
            "organization": "WTSI"
        }
    ]

### Show information about a beacon

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/beacons/wtsi

Response:

    {
        "aggregator": false,
        "id": "wtsi",
        "name": "Wellcome Trust Sanger Institute",
        "organization": "WTSI"
    }

Alternatively, just filter the list using the optional "beacon" parameter. Example:

    GET http://localhost:8080/beacon-of-beacons/rest/beacons?beacon=wtsi

Response:

    [
        {
            "aggregator": false,
            "id": "wtsi",
            "name": "Wellcome Trust Sanger Institute",
            "organization": "WTSI"
        }
    ]

### List supported genomes

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/references

Response:

    [
        {
            "item": "HG38"
        },
        {
            "item": "HG19"
        },
        {
            "item": "HG18"
        },
        {
            "item": "HG17"
        },
        {
            "item": "HG16"
        }
    ]

### List supported chromosomes

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/chromosomes

Response:

    [
        {
            "item": "CHR22"
        },
        {
            "item": "CHR21"
        },
        {
            "item": "CHR20"
        },
        {
            "item": "CHR19"
        },
        {
            "item": "CHR18"
        },
        {
            "item": "CHR17"
        },
        {
            "item": "CHR16"
        },
        {
            "item": "CHR15"
        },
        {
            "item": "CHR14"
        },
        {
            "item": "CHR13"
        },
        {
            "item": "CHR12"
        },
        {
            "item": "CHR11"
        },
        {
            "item": "CHR10"
        },
        {
            "item": "CHR9"
        },
        {
            "item": "CHR8"
        },
        {
            "item": "CHR7"
        },
        {
            "item": "CHR6"
        },
        {
            "item": "CHR5"
        },
        {
            "item": "CHR4"
        },
        {
            "item": "CHR3"
        },
        {
            "item": "CHR2"
        },
        {
            "item": "CHR1"
        },
        {
            "item": "CHRX"
        },
        {
            "item": "CHRY"
        },
        {
            "item": "CHRMT"
        }
    ]

### List supported alleles

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/alleles

Response:

    [
        {
            "item": "A"
        },
        {
            "item": "C"
        },
        {
            "item": "G"
        },
        {
            "item": "T"
        },
        {
            "item": "D"
        },
        {
            "item": "I"
        }
    ]

### Query a specific beacon

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/responses/lovd?chrom=1&pos=808922&allele=T

Response:

    {
        "beacon": {
            "aggregator": false,
            "id": "lovd",
            "name": "Leiden Open Variation",
            "organization": "UCSC"
        },
        "query": {
            "allele": "T",
            "chromosome": "CHR1",
            "position": 808922,
            "reference": null
        },
        "response": false
    }

As you can see, the beacon responded with its own info, the query details and a response field denoting whether a match was found (true) or not (false). Null value is used to describe a problem, e.g. an invalid query. Some beacons, for example, do not support allele strings of length>1 or X/Y chromosomes.

### Query beacon with a specific genome

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/responses/amplab?chrom=15&pos=41087870&allele=A&ref=hg19

Response:

    {
        "beacon": {
            "aggregator": false,
            "id": "amplab",
            "name": "AMPLab",
            "organization": "APMLab"
        },
        "query": {
            "allele": "A",
            "chromosome": "CHR15",
            "position": 41087870,
            "reference": "HG19"
        },
        "response": true
    }

### Query all beacons

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/responses?chrom=14&pos=106833421&allele=A

Response:

    [
        {
            "beacon": {
                "aggregator": false,
                "id": "thousandgenomes",
                "name": "1000 Genomes Project",
                "organization": "Google"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "thousandgenomes-phase3",
                "name": "1000 Genomes Project - Phase 3",
                "organization": "Google"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "amplab",
                "name": "AMPLab",
                "organization": "APMLab"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": true
        },
        {
            "beacon": {
                "aggregator": true,
                "id": "bob",
                "name": "Beacon Network",
                "organization": "Global Alliance for Genomics and Health"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": true
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "cafe-cardiokit",
                "name": "Cafe CardioKit",
                "organization": "University of Leicester"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": true,
                "id": "cafe-variome",
                "name": "Cafe Variome",
                "organization": "University of Leicester"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "cafe-central",
                "name": "Cafe Variome Central",
                "organization": "University of Leicester"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "clinvar",
                "name": "ClinVar",
                "organization": "UCSC"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "ebi",
                "name": "EMBL-EBI",
                "organization": "EBI"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "curoverse-ref",
                "name": "GA4GH Example Data",
                "organization": "Curoverse"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": true,
                "id": "google",
                "name": "Google Genomics Public Data",
                "organization": "Google"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "platinum",
                "name": "Illumina Platinum Genomes",
                "organization": "Google"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "kaviar",
                "name": "Known VARiants",
                "organization": "Institute for Systems Biology"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "lovd",
                "name": "Leiden Open Variation",
                "organization": "UCSC"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "ncbi",
                "name": "NCBI",
                "organization": "NCBI"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": true
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "curoverse",
                "name": "PGP",
                "organization": "Curoverse"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "uniprot",
                "name": "UniProt",
                "organization": "UCSC"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        },
        {
            "beacon": {
                "aggregator": false,
                "id": "wtsi",
                "name": "Wellcome Trust Sanger Institute",
                "organization": "WTSI"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": false
        }
    ]

### Filter reponses for a specific beacon

Query:

    GET http://localhost:8080/beacon-of-beacons/rest/responses?chrom=14&pos=106833421&allele=A&beacon=amplab

Response:

    [
        {
            "beacon": {
                "aggregator": false,
                "id": "amplab",
                "name": "AMPLab",
                "organization": "APMLab"
            },
            "query": {
                "allele": "A",
                "chromosome": "CHR14",
                "position": 106833421,
                "reference": null
            },
            "response": true
        }
    ]

### Aggregate responses of all beacons via beacon of beacons

If you want to utilize the "beacon of beacons" feature and are only interested in whether any of the existing beacons have a particular variant, treat Beacon Network as a beacon itself and let it perform the aggregation. Query:

    GET http://localhost:8080/beacon-of-beacons/rest/responses/bob?chrom=14&pos=106833421&allele=D

Response:

    {
        "beacon": {
            "aggregator": true,
            "id": "bob",
            "name": "Beacon Network",
            "organization": "Global Alliance for Genomics and Health"
        },
        "query": {
            "allele": "D",
            "chromosome": "CHR14",
            "position": 106833421,
            "reference": null
        },
        "response": true
    }