Beacon API Examples¶
The Beacon API consists of the following endpoints:
/
beacon information endpoint;/service-info
GA4GH compliant information endpoint;/query
- retrieving and filtering information from the beacon.
For the full specification consult: Beacon API 1.0.0+ specification.
The Beacon API specification allows for additional properties, thus we add the following fields to
/query
endpoint to handle wildcard responses:
referenceBases
alternateBases
variantType
And variant location information to determine the region:
start
end
The requests are validated against a JSON schema, while for the responses we validate (via unit tests) that they adhere to the required format.
Info Endpoint¶
$ curl -X GET 'http://localhost:5050/'
Example Response:
{
"id": "localhost:5050",
"name": "EGA Beacon",
"apiVersion": "1.0.0",
"organization": {
"id": "CSC",
"name": "CSC - IT Center for Science",
"description": "Finnish expertise in ICT for research, education, culture and public administration",
"address": "Keilaranta 14, Espoo, finland",
"welcomeUrl": "https://www.csc.fi/",
"contactUrl": "https://www.csc.fi/contact-info",
"logoUrl": "https://www.csc.fi/documents/10180/161914/CSC_2012_LOGO_RGB_72dpi.jpg",
"info": {
"orgInfo": "CSC represents Finland in the ELIXIR partner nodes"
}
},
"description": "Beacon API Web Server based on the GA4GH Beacon API",
"version": "1.0.0",
"welcomeUrl": "https://ega-archive.org/",
"alternativeUrl": "https://ega-archive.org/",
"createDateTime": "2018-07-25T00:00:00Z",
"updateDateTime": "2018-12-01T10:28:07Z",
"datasets": [{
"id": "urn:hg:1000genome",
"name": "1000 genome",
"externalUrl": "ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/release/20130502/",
"description": "Data from 1000 genome project",
"assemblyId": "GRCh38",
"variantCount": 84360986,
"callCount": 79423363,
"sampleCount": 2504,
"version": "v0.4",
"info": {
"accessType": "PUBLIC"
},
"createDateTime": "2013-05-02T12:00:00Z",
"updateDateTime": "2013-05-02T12:00:00Z"
}],
"sampleAlleleRequests": [{
"alternateBases": "C",
"referenceBases": "T",
"referenceName": "MT",
"start": 9,
"assemblyId": "GRCh38",
"includeDatasetResponses": "ALL"
}, {
"alternateBases": "A",
"referenceBases": "G",
"referenceName": "MT",
"start": 7599,
"assemblyId": "GRCh38",
"datasetIds": ["urn:hg:exampleid-mt"],
"includeDatasetResponses": "HIT"
}, {
"variantType": "SNP",
"referenceBases": "G",
"referenceName": "Y",
"start": 7267243,
"assemblyId": "GRCh38"
}],
"info": {
"key": "value"
}
}
GA4GH Info Endpoint¶
$ curl -X GET 'http://localhost:5050/service-info'
Example Response:
{
"id": "localhost:5050",
"name": "GA4GHBeacon at CSC",
"type": "org.ga4gh:beacon:1.1.0",
"description": "Beacon API Web Server based on the GA4GH Beacon API",
"organization": {
"name": "CSC - IT Center for Science",
"url": "https://www.csc.fi/"
},
"contactUrl": "https://www.csc.fi/contact-info",
"documentationUrl": "https://beacon-network.readthedocs.io/en/latest/",
"createdAt": "2019-09-04T12:00:00Z",
"updatedAt": "2019-09-05T05:55:18Z",
"environment": "prod",
"version": "1.7.2"
}
Query Endpoint¶
An example GET
request and response to the query
endpoint:
$ curl -X GET \
'http://localhost:5050/query?referenceName=MT&referenceBases=A&start=14036&assemblyId=GRCh38&alternateBases=G'
Example Request:
{
"beaconId": "localhost:5050",
"apiVersion": "1.0.0",
"exists": true,
"alleleRequest": {
"referenceName": "MT",
"start": 14036,
"referenceBases": "A",
"assemblyId": "GRCh38",
"datasetIds": [],
"includeDatasetResponses": "NONE",
"alternateBases": "G"
},
"datasetAlleleResponses": []
}
An example POST
request and response to the query
endpoint:
$ curl -X POST \
'http://localhost:5050/query' \
-d '{"referenceName": "MT", \
"start": 14036, \
"referenceBases": "A", \
"alternateBases": "G", \
"assemblyId": "GRCh38", \
"includeDatasetResponses": "HIT"}'
Example Response:
{
"beaconId": "localhost:5050",
"apiVersion": "1.0.0",
"exists": true,
"alleleRequest": {
"referenceName": "MT",
"start": 14036,
"referenceBases": "A",
"assemblyId": "GRCh38",
"datasetIds": [],
"includeDatasetResponses": "HIT",
"alternateBases": "G"
},
"datasetAlleleResponses": [{
"datasetId": "urn:hg:1000genome",
"referenceName": "MT",
"externalUrl": "ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/release/20130502/",
"note": "Data from 1000 genome project",
"sampleCount": 2,
"callCount": 2534,
"exists": true,
"referenceBases": "A",
"alternateBases": "G",
"start": 14036,
"end": 14037,
"variantType": "SNP",
"frequency": 0.000789266,
"variantCount": 1,
"info": {
"accessType": "PUBLIC"
}
}]
}