This is Version 2 specifications and will soon be deprecated. We strongly recommend upgrading to Version 4 specifications to ensure compatibility and take advantage of the latest features and improvements. Please look at our Wikki page to see the latest updates.
This API specification is defined in the context of the EJPRD project, complying with the latest Beacon v2 Specification.
In this work, we present API specification for querying RD patient registries, biobanks and similar resources at the safe record level (i.e, resources whose available assets are described by RD patient data). Resources that implement this specification would ideally collect data based on the set of common data elements for rare diseases registration, as recommended by the European commission Joint Research Centre. In this specification, where possible, we also make use of ontological terms recommended by the CDE semantic data model group.
- Try out this API in Swagger
- Specification
- Query Endpoints
- Authentication using Header(s)
- Understanding the query
- Understanding the response with ranges (for /individuals and /biospecimens)
- Informational Endpoints
Latest version (v2.0) of this specification is available on Swagger here: https://app.swaggerhub.com/apis/DVS6_1/virtual-platform_beacon_api/v2.0#/
The request and response conforms to the Beacon Reference Framework. This Specification defines two types of endpoints - The Query Endpoints and The Informational Endpoints.
Informational Endpoints are simple GET requests without needing a request body, and respond with information relavant to this Beacon Specification. These are: /info, /configuration, /entry_types, /filtering_terms and /map. A special /service-info endpoint (also a GET request), responds with metadata relevant to this Beacon using the GA4GH ServiceInfo format.
Query Endpoints require the requester to provide a JSON body and send request using the POST method. This document defines three query endpoints to query resources using filters - /individuals, /biosamples and /catalogs.
This specification defines POST endpoints to request information about resources. Each endpoint makes use of the Filters capability of the Beacon API.
HTTP Request Method : POST
/individuals endpoint returns the maximum value of individuals within a specified range from a RD resource. Filters are provided as a part of the body while using a HTTP POST request to query resources.
Please do not use HTTP GET method to query the individuals endpoint, as it is not permitted per this specification, and will result in a 403 error response.
Note: Elements within arrays in value fields are treated as ORs
CDE Concept | CDE Term | Beacon Filter Type | ID | Operator | Permitted Values |
---|---|---|---|---|---|
Sex | obo:NCIT_C28421 | Alphanumerical | NCIT_C28421 | = | NCIT_C16576 |
NCIT_C20197 | |||||
NCIT_C124294 | |||||
NCIT_C17998 | |||||
An array of any of the above | |||||
Disease or Disorder | obo:NCIT_C2991 | Ontology | A single value or an array of orphanet terms. e.g. ordo:Orphanet_558 or [ordo:Orphanet_558, ordo:Orphanet_773] | NA | |
Phenotype | sio:SIO_010056 | Ontology | A single value or an array of HPO terms. e.g. HP:0001251 or [HP:0001251, HP:0012250] | NA | |
Causative Genes | edam:data_2295 | Alphanumerical | data_2295 | = | any HGNC gene symbol or array of HGNC symbols |
Age this year | obo:NCIT_C83164 | Numerical | NCIT_C83164 | =, >=, >, <=, < | any integer |
Symptom Onset | obo:NCIT_C124353 | Numerical | NCIT_C124353 | =, >=, >, <=, < | any integer |
Age at diagnosis | obo:NCIT_C156420 | Numerical | NCIT_C156420 | =, >=, >, <=, < | any integer |
Sex: The biological sex of an individual patient.
Disease or Disorder: All rare diseases that have been diagnosed within an individual, to encompase, but not distinguish between all levels of diagnosis such as definitive, differential, provisional, etc.,
Phenotype: HPO terms of all phenotypes observed within an individual.
Causative Genes: All genes which have been deemed as causative of one or more of the diagnosed rare diseases in an individual, encompassing and not distinguishing between all certainty levels of casuality.
Age this year: Age at the end of the current year. -/+ will be added to all age queries when executed by the query engine at the resource.
Symptom Onset: Age at the manifestation of a rare disease. For individuals with more than one rare disease, this filter will look at all age of manifestations independently. -/+ will be added to all age queries when executed by the query engine at the resource.
Age at diagnosis: Age at the diagnosis of a rare disease. For individuals with more than one rare disease, this filter will look at all age of manifestations independently. -/+ will be added to all age queries when executed by the query engine at the resource.
EXAMPLE /individuals REQUEST
{
"meta": {
"apiVersion": "v2.0"
},
"query": {
"filters": [
{
"id": "ordo:Orphanet_34587",
"includeDescendantTerms": true
},
{
"id": "data_2295",
"value": "LAMP2",
"operator": "="
},
{
"id": "NCIT_C28421",
"operator": "=",
"value": "NCIT_C16576"
}
],
"requestedGranularity": "boolean"
}
}
EXAMPLE /individuals RESPONSE
{
"meta": {
"apiVersion": "v2.0",
"beaconId": "Responding unique Beacon ID in reverse domain name notation",
"returnedGranularity": "count"
},
"response": {
"resultSets": [
{
"id": "Vivify",
"type": "dataset",
"exists": true,
"resultCount": 80,
"info": {
"resultCountDescription": {
"minRange": 71,
"maxRange": 80
},
"contactPoint": "admin",
"contactEmail": "admin@cafevariome.org",
"contactURL": "rdnexusdev.molgeniscloud.org/cv2/"
}
}
]
},
"responseSummary":{
"exists": true,
"numTotalResults": 80
}
}
The "resultCount" attribute in the above response is the maximum value of whatever range that result is within, rather than giving out the actual count of individuals. More information on responding using ranges can be found here
The filter SHOULD be one of the terms from the filters and permitted values table. Please note that not all resources will support all of the filters. In such cases the response MUST include a warning message in the 'info' part indicating which requested filters are unsupported and these were not included in the query.
The "includeDescendantTerms" is used to query for entities associated with the submitted bio-ontology term(s). The default and assumed value of includeDescendantTerms is false . If the parameter is set to true, then the request implies that a hierarchical ontology search is requested.
EXAMPLE warning when unsupported filters are requested
{
"meta": {
"beaconId": "org.rd-connect.beacon",
"apiVersion": "v2.0.0-draft.4",
"returnedGranularity": "count",
"receivedRequestSummary": {
"apiVersion": "v2.0",
"requestedSchemas": [
{
"entityType": "individuals",
"schema": "beacon-individual-v2.0.0-draft.4"
}
],
"filters": [
[
{
"id": [
"ordo:Orphanet_730",
"ordo:Orphanet_2730"
]
},
{
"id": "NCIT_C28421",
"operator": "=",
"value": "NCIT_C20197"
},
{
"id": "data_2295",
"operator": "=",
"value": "100"
},
{
"id": "NCIT_C83164",
"operator": ">=",
"value": "0"
},
{
"id": "NCIT_C124353",
"operator": ">=",
"value": "0"
},
{
"id": "NCIT_C156420",
"operator": ">=",
"value": "0"
}
]
]
},
"returnedSchemas": [
{
"entityType": "individuals",
"schema": "beacon-individual-v2.0.0-draft.4"
}
]
},
"responseSummary": {
"exists": false,
"numTotalResults": 0
},
"info": {
"warnings": {
"unsupportedFilters": [
"NCIT_C83164",
"NCIT_C124353",
"NCIT_C156420"
]
}
},
"response": {
"resultSets": [
{
"id": "datasetBeacon",
"type": "individuals",
"exists": false,
"resultCount": 0
}
]
}
}
HTTP Request Method : POST
Similarly to the /individuals
endpoint, /biosamples
endpoint returns the maximum value of biosamples within a specified range from an RD resource (usually the resource is a Biobank). Queries are performed in the same way as for /individuals
endpoint, adding filters in the body of the request.
Please do not use HTTP GET method to query the biosamples endpoint, as it is not permitted per this specification, and will result in a 403 error response.
Note: Elements within arrays in value fields are treated as ORs
Concept | Ontological Term | Beacon Filter Type | ID | Operator | Permitted Values |
---|---|---|---|---|---|
Sex | obo:NCIT_C28421 | Alphanumerical | NCIT_C28421 | = | NCIT_C16576 |
NCIT_C20197 | |||||
NCIT_C124294 | |||||
NCIT_C17998 | |||||
An array of any of the above | |||||
Disease or Disorder | obo:NCIT_C2991 | Ontology | A single value or an array of orphanet terms. e.g. ordo:Orphanet_558 or [ordo:Orphanet_558, ordo:Orphanet_773] | NA | |
Year of birth | obo:NCIT_C83164 | Numerical | NCIT_C83164 | =, >=, >, <=, < | any integer |
Age at diagnosis | obo:NCIT_C156420 | Numerical | NCIT_C156420 | =, >=, >, <=, < | any integer |
Biospecimen Type | obo:NCIT_C70713 | Alphanumerical | NCIT_C70713 | = | OBI_0000655 (blood specimen) |
OBI_0002512 (bone marrow) | |||||
OBIB_0000036 (buffy coat) | |||||
CL_2000001 (peripheral blood mononuclear cell) | |||||
OBI_0100016 (blood plasma specime) | |||||
OBI_0100017 (blood serum) | |||||
UBERON_0007795 (ascites fluid) | |||||
OBI_0002502 (cerebrospinal fluid) | |||||
OBI_0002507 (saliva) | |||||
OBI_0002503 (feces) | |||||
OBI_0000651 (urine) | |||||
OBI_0002599 (swab) | |||||
OBI_2000009 (bodily fluid specimen) | |||||
OBI_1200000 (FFPE specimen) | |||||
OBI_0000922 (frozen specimen) | |||||
OBI_0001472 (specimen with known storage state) | |||||
OBI_0001051 (DNA extract) | |||||
OBI_0000880 (RNA extract) | |||||
OBI_0001479 (specimen from organism) | |||||
An array of any of the above |
Sex: The biological sex of the person the biosample belongs to.
Disease or Disorder: All rare diseases that have been diagnosed from the biosample, to encompase, but not distinguish between all levels of diagnosis such as definitive, differential, provisional, etc.,
Year of birth: The year of birth of the person who the biosample belongs to
Age at diagnosis: Age at the diagnosis of a rare disease. For biosamples with more than one rare disease, this filter will look at all age of manifestations independently. -/+ will be added to all age queries when executed by the query engine at the resource.
Biospecimen Type: One or more biospecimen type. The list is a list of ontology terms taken from MIABIS
EXAMPLE /biosamples REQUEST
{
"meta": {
"apiVersion": "v2.0"
},
"query": {
"filters": [
{
"id": "ordo:Orphanet_34587"
},
{
"id": "obo:NCIT_C70713",
"operator": "=",
"value": "OBI_0000655"
}
],
"requestedGranularity": "count"
}
}
EXAMPLE /biosamples RESPONSE
{
"meta": {
"beaconId": "biobank beacon",
"apiVersion": "v2.0.0",
"returnedGranularity": "count",
"receivedRequestSummary": {
"apiVersion": "2.0",
"filters": [
{
"id": "ordo:Orphanet_34587"
},
{
"id": "obo:NCIT_C70713",
"operator": "=",
"value": "OBI_0000655"
}
],
"requestedGranularity": "count",
"testMode": false
},
"returnedSchemas": [
{
"entityType": "biosample",
"schema": "beacon-biosample-v2.0.0",
"name": "Default schema for a biological sample",
"url": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2-Models/main/BEACON-V2-Model/biosamples/defaultSchema.json",
"version": "v2.0.0"
}
]
},
"responseSummary": {
"exists": true,
"numTotalResults": 100
},
}
Notes about the resultCount
and unsupported filters for the /individuals
endpoint apply also for biospecimens
Method: POST
/catalogs endpoint returns the metadata of RD resources, using as response, a model compatible with the Resource Metadata Schema. Filters are provided as a part of the body while using a POST request to query resources. Available filters correspond also to dcat properties from the Resource Metadata Schema
Note: Elements within arrays in value fields are treated as ORs
Metadata Schema Concept | Metadata Schema Term | Beacon Filter Type | ID | Operator | Permitted Values |
---|---|---|---|---|---|
Disease or Disorder | dcat:theme | Ontology | A single value or an array of orphanet terms in CURIE syntax prefixed with `ordo:`e.g. ordo:Orphanet_558 or [ordo:Orphanet_558, ordo:Orphanet_773] | NA | |
Phenotype | sio:SIO_010056 | Ontology | A single value or an array of HPO terms prefixed with `HP:` e.g. HP:0001251 or [HP:0001251, HP:0012250] | NA | |
Resource Types | rdf:type | Alphanumerical | A single value or an array of values representing a resource type of the resource. It must be one of the types defined in EJP Resource Metadata Schema | = | ejprd:PatientRegistry |
ejprd:Biobank | |||||
ejprd:Guideline | |||||
dcat:Dataset | |||||
An array of any of the above | |||||
ID | NA | Alphanumerical | id | = | any String |
Name | dct:title | Alphanumerical | The name of the resource | = | any String |
Description | dct:description | Alphanumerical | The description of the resource | = | any String |
Disease or Disorder: All rare diseases that are associated within a catalog. It corresponds to the dcat:theme
property of the Resource Metadata Schema. The values follow CURIE syntax and use the ordo:
prefix.
Phenotype: HPO terms of all phenotypes observed within a catalog of rare disease resources. The values follow CURIE syntax and use the HP:
prefix.
ID: The resource identifier ID within the catalog. It corresponds to the identifier of the RDF resource
Name: The name of the resource in the catalog. It corresponds to the dct:title
of the Resource Metadata Schema
Description: The description of the resource in the catalog. It corresponds to the dct:description
property of the Resource Metadata Schema
Organisation: The organisation that owns the resouce. It corresponds to the dct:publisher property.
Resource Types: Types of resources within the catalog. Permitted values for this filter are the type of resources in the Resource Metadata Schema: ejprd:PatientRegistry
, ejprd:Biobank
, ejprd:Guideline
, dcat:Datasest
or an array of any of these values.
The response is a Beacon Collection response that corresponds to a Resource described by the Resource Metadata Schema. Depending on the resource type, the properties may slighlty differ: for example some resource types can have properties that others don't have. Notice that an important field in all resources is the @context
that specifies the semantics of the properties returned. It must be the link to the json-ld-contexts/ejprd-context.json
file in this repository. The schemas for each specific resource are in the /schemas
directory.
In the meta section of the response, the returnedSchemas
object must specify the correct json schema for the resource. An example is:
"returnedSchemas": [
{
"entityType": "resources",
"schema": "ejprd-biobank-registry-v1.0.0",
"name": "EJPRD schema for biobank and patient registry",
"url": "https://raw.githubusercontent.com/ejp-rd-vp/vp-api-specs/main/schemas/biobank-registry-schema.json",
"version": "v1.0.0"
}
]
EXAMPLE /catalogs REQUEST
{
"meta":{
"apiVersion": "v2.0"
},
"query": {
"filters": [
{
"id": "ordo:Orphanet_730"
},
{
"id": "rdf:type",
"operator": "=",
"value": "ejprd:Biobank"
}
],
"requestedGranularity": "record"
}
}
The following is an example response
EXAMPLE /catalogs RESPONSE
{
"meta": {
"beaconId": "ejprd.beacon.directory.bbmri-eric.eu",
"apiVersion": "v2.0.0",
"returnedGranularity": "record",
"receivedRequestSummary": {
"apiVersion": "2.0",
"requestedSchemas": [],
"filters": [
{
"id": "ordo:Orphanet_730"
},
{
"id": "rdf:type",
"operator": "=",
"value": "ejprd:Biobank"
}
],
"requestParameters": {},
"includeResultsetResponses": "HIT",
"pagination": {
"skip": 0,
"limit": 50
},
"requestedGranularity": "record",
"testMode": false
},
"returnedSchemas": [
{
"entityType": "resources",
"schema": "ejprd-resources-v1.0.0",
"name": "EJPRD schema for resources",
"url": "https://raw.githubusercontent.com/ejp-rd-vp/vp-api-specs/main/schemas/biobank-registry-schema.json",
"version": "v1.0.0"
}
]
},
"responseSummary": {
"exists": true,
"numTotalResults": 1
},
"beaconHandovers": [],
"response": {
"resultSets": [
{
"resultsCount": 1,
"results": [{
"@context": "https://raw.githubusercontent.com/ejp-rd-vp/vp-api-specs/main/json-ld-contexts/ejprd-context.json",
"@id": "biobank-1:collection:collection-1",
"@type": "ejprd:Biobank",
"title": "Rare Disease Biobank",
"logo": "http://raredisease.biobank.eu/logo.png",
"description": "Rare disease biobank with data about muscular distrophy",
"populationCoverage": "European",
"theme": "ordo:Orphanet_730",
"vpConnection": "ejprd:VPContentDiscovery",
"landingPage": ["http://biobank.raredisease.org"],
"personalData": "true",
"language": "EN",
"publisher": {
"@id": "biobank-1",
"title": "Biobank hosting collection",
"description": "The biobank that hosts the collection",
"spatial": {
"title": "Italy"
}
}
}]
}
]
}
}
Notes about the unsupported filters for the /individuals
endpoint apply also for catalogs
Since the specification allows for record level queries of individuals, additional information is required in the request header to verify the requester is authorised:
Header Attribute | Header Value | Purpose |
---|---|---|
auth-key | Token provided by resource | Indicates requester is authorised (required) |
auth-token | Bearer token, True, False | Indicates requesting user's logged in status (optional) |
authentication-url | Bearer token authentication provider | Enables validation of bearer token (optional) |
Note: Presence of a bearer token is equivalent to auth-token:True
Note: Implementers can provide distinct auth-keys to each requester or a single auth-key to all requesters.
To see this live in action in Swagger UI, see Authentication in Swagger.
Method: POST
There are 3 types of Beacon queries that this specification currently supports:
The following JSON body depicts the typical usage of filters to query resources.
- Alphanumeric filters require the use of id, operator(=) and value properties.
- Ontology filters only require the 'id' property to query resources.
- Numeric filters also require id, operator and value properties. These filters differ from the alphanumeric filters as it is also possible to use comparison operators (>=,>,<=,<) along with '='.
These usage rules are illustrated using a general syntax as below:
{
"meta": {
"apiVersion": "v2.0"
},
"query": {
"filters": [
{
"id": "AlphanumericFilter_id",
"operator": "=",
"value":"AlphanumericFilter_value"
},
{
"id": "AlphanumericFilter_id",
"operator": "=",
"value":"AlphanumericFilter_value"
},
{
"id": "OntologyFilter:value"
}
],
"requestedGranularity": "boolean"
}
}
As shown above, different types of filters can be sent in a single query. These are further elucidated below.
{
"query": {
"filters": [
{
"id": "ordo:Orphanet_34587"
},
{
"id": "data_2295",
"operator": "=",
"value": "LAMP2"
}
]
}
}
This filter is asking for individuals that have been diagnosed with Danon disease (ordo:Orphanet_34587) and where LAMP2 gene has been identified as causative. These filters are handled independently, this means that individuals with Danon disease where LAMP2 has been identified as a causative gene, specifically for Danon disease, will match the query. It also means that individuals with Danon disease and where LAMP2 has been identified as a causative gene for a second rare disease, other than Danon disease, will also match this query.
To query for individuals with more than one instance of any of the filters you can send multiple of the same filter, such as in the below example:
Ontology Filter Example:
{
"query":
{
"filters": [
{
"id": "ordo:Orphanet_34587"
},
{
"id": "ordo:Orphanet_1653"
}
]
}
}
This query is looking for individuals with Danon disease ("ordo:Orphanet_34587") AND Dentin dysplasia ("ordo:Orphanet_1653").
Alphanumeric Filter example:
{
"query":
{
"filters": [
{
"id": "Available Materials",
"operator": "=",
"value": "RNA sequence"
},
{
"id": "Available Materials",
"operator": "=",
"value": "Whole Genome Sequence"
}
]
}
}
This query is looking if there are any individuals with RNA sequence information AND Whole Genome Sequence information available.
Ontology Filter using Array Example:
{
"query":
{
"filters": [
{
"id": ["ordo:Orphanet_34587","ordo:Orphanet_1653"]
}
]
}
}
This query is looking for individuals either with Danon disease (ordo:Orphanet_34587) OR Dentin dysplasia (ordo:Orphanet_1653).
Note: There are no OR operators available between filters with beacon queries.
All of the defined filters are optional, the user can provide as many or as few as wanted and the resource does not have to implement all filters.And if the user does not provide any filters all the list of entities will be returned.
If a user sends a query with a filter not supported by a resource, then the resource should complete the query but ignore the unsupported filter(s) and respond as usual, but with a warning noting that certain filters were ignored as they are unsupported.
The warning messages will be provided within the info
section of the Beacon.
EXAMPLE REQUEST
{
"meta":{
"apiVersion": "v2.0"
},
"query":{
"filters": [
{
"id": "ordo:Orphanet_34587"
},
{
"id": "data_2295",
"value": "LAMP2",
"operator": "="
},
{
"id": "NCIT_C28421",
"operator": "=",
"value": "NCIT_C16576"
}
],
"requestedGranularity": "boolean"
}
}
This request is asking for females with Danon disease with LAMP2 being identified as a causative gene.
This request is sent to a resource which does not hold information about causative genes but does hold information about diagnoses and sex, an example response which could be returned is outlined below:
EXAMPLE WARNING RESPONSE
{
"meta": {
"apiVersion": "v2.0",
"beaconId": "Responding unique Beacon ID in reverse domain name notation",
"returnedGranularity":"count"
},
"response": {
"resultSets": [
{
"id": "Vivify",
"type": "dataset",
"exists": true,
"resultCount": 20,
"info": {
"resultCountDescription": {
"minRange": 11,
"maxRange": 20
},
"contactPoint": "admin",
"contactEmail": "admin@cafevariome.org",
"contactURL": "rdnexusdev.molgeniscloud.org/cv2/"
}
}
]
},
"responseSummary":{
"exists": "true",
"numTotalResults": 20
},
"info": {
"warnings":{
"unsupportedFilters": [
"data_2295"
]
}
}
}
This response provides a warning message within the info section advising of unsupported filters which were ignored when the query was processed by the resources query engine. Please see the info part of the IndividualResponse schema on swagger.
In the examples of the response for the /individuals
and /biosamples
endpoints, information of the resultant dataset matching the query is provided within the resultSets
attribute.
To provide flexibility for implementers between using a range, the info
section of each resultant dataset in resultSets
need to conform to the following standardised structure:
"info": {
"resultCountDescription": {
"minRange": N,
"maxRange": N
},
"contactPoint": "Person/point of contact",
"contactEmail": "Email for contact regarding this dataset/resource",
"contactURL": "URL of the implementer"
}
Note: Here, N is an integer where the implementer can respond with "minRange" & "maxRange" (if employing a range) - the maximum value of whatever range that result is within, whereupon the "maxRange" value should match the "resultCount" value and the "numTotalResults" value.
Example response employing a range:
{
"meta": {
"apiVersion": "v2.0",
"beaconId": "Responding unique Beacon ID in reverse domain name notation",
"returnedGranularity": "count"
},
"response": {
"resultSets": [
{
"id": "Vivify",
"type": "dataset",
"exists": true,
"resultCount": 80,
"info": {
"resultCountDescription": {
"minRange": 71,
"maxRange": 80
},
"contactPoint": "admin",
"contactEmail": "admin@cafevariome.org",
"contactURL": "rdnexusdev.molgeniscloud.org/cv2/"
}
}
]
},
"responseSummary":{
"exists": true,
"numTotalResults": 80
}
}
In this example, the result could be a count of individuals between 71 to 80 (the resource only responds with ranges of size 10).
This specification defines GET endpoints to request information about resources.
HTTP Request Method : GET
/info returns the information about the Beacon.
{
"meta": {
"beaconId": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"apiVersion": "v2.0",
"returnedSchemas": {
"entityType": "Info Endpoint",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/endpoints.json"
}
},
"response": {
"id": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"name": "Cafe Variome Beacon",
"apiVersion": "v2.0",
"createDateTime": "2021-02-03 15:07 BST",
"updateDateTime": "2022-10-05 17:18 BST",
"description": "This Beacon is based on the Beacon specification by GA4GH. Implemented by The Brookeslab @ University of Leicester, this Beacon contains all informational endpoints along with individuals and biosamples discovery.",
"environment": "dev",
"organization": {
"id": "ULEIC",
"name": "University of Leicester",
"address": "University Road, Leicester, LE1 7RH",
"contactUrl": "mailto:admin@cafevariome.org?subject=Beacon Info",
"logoUrl": "https://rdnexusdev.molgeniscloud.org/cv2/resources/images/logos/cafevariome-logo-full.png",
"welcomeUrl": "https://le.ac.uk/health-data-research/",
"description": "Cafe Variome is a flexible data discovery software. Cafe Variome + Beacon makes discovering genomic data easier."
},
"welcomeUrl": "https://www.cafevariome.org/",
"alternativeUrl": "https://le.ac.uk/health-data-research/activities/"
}
}
HTTP Request Method : GET
/service-info returns the information about the basic metadata concerning its service, based on the reference specification.
{
"id": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"name": "Cafe Variome Beacon",
"type": {
"artifact": "beacon",
"group": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"version": "v2.0"
},
"organization": {
"name": "University of Leicester",
"url": "https://www.le.ac.uk"
},
"contactUrl": "mailto:admin@cafevariome.org?subject=Beacon Service Info",
"createdAt": "2021-02-03 15:07 BST",
"updatedAt": "2022-10-06 11:56 BST",
"description": "This service provides information about Beacon deployed by Cafe Variome Software.",
"documentationUrl": "https://cafe-variome.gitbook.io/cafe-variome-docs/features/beacon/beacon-api",
"environment": "dev",
"version": "v2.0"
}
HTTP Request Method : GET
/configuration returns the information about the Beacon.
{
"meta": {
"beaconId": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"apiVersion": "v2.0",
"returnedSchemas": [
{
"entityType": "individuals",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/individuals/defaultSchema.json"
},
{
"entityType": "biosamples",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
]
},
"response": {
"$schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/configuration/beaconConfigurationSchema.json",
"entryTypes": {
"Individuals": {
"id": "Individuals",
"name": "Individuals",
"ontologyTermForThisType": {
"id": "NCIT:C25190"
},
"partOfSpecification": "v2.0",
"defaultSchema": {
"id": "beacon-v2-individual",
"name": "Default Schema for Individuals",
"referenceToSchemaDefinition": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/individuals/defaultSchema.json"
}
},
"Biosamples": {
"id": "Biosamples",
"name": "Biosamples",
"ontologyTermForThisType": {
"id": "NCIT:C43412"
},
"partOfSpecification": "v2.0",
"defaultSchema": {
"id": "beacon-v2-biosample",
"name": "Default Schema for Biosamples",
"referenceToSchemaDefinition": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
}
},
"maturityAttributes": {
"productionStatus": "DEV"
},
"securityAttributes": {
"defaultGranularity": "count"
}
}
}
HTTP Request Method : GET
/entry-types returns the information about the Beacon.
{
"meta": {
"beaconId": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"apiVersion": "v2.0",
"returnedSchemas": [
{
"entityType": "individuals",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/individuals/defaultSchema.json"
},
{
"entityType": "biosamples",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
]
},
"response": {
"entryTypes": {
"Individuals": {
"id": "Individuals",
"name": "Individuals",
"ontologyTermForThisType": {
"id": "NCIT:C25190"
},
"partOfSpecification": "v2.0",
"defaultSchema": {
"id": "beacon-v2-individual",
"name": "Default Schema for Individuals",
"referenceToSchemaDefinition": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2-Models/main/BEACON-V2-draft4-Model/individuals/defaultSchema.json"
}
},
"Biosamples": {
"id": "Biosamples",
"name": "Biosamples",
"ontologyTermForThisType": {
"id": "NCIT:C43412"
},
"partOfSpecification": "v2.0",
"defaultSchema": {
"id": "beacon-v2-biosample",
"name": "Default Schema for Biosamples",
"referenceToSchemaDefinition": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
}
}
}
}
HTTP Request Method : GET
/filtering_terms returns the information about the Beacon.
{
"meta": {
"beaconId": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"apiVersion": "v2.0",
"returnedSchemas": [
{
"entityType": "individuals",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/individuals/defaultSchema.json"
},
{
"entityType": "biosamples",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
]
},
"response": {
"filteringTerms": [
{
"id": "NCIT_C28421",
"label": "Sex. Permitted values: NCIT_C16576, NCIT_C20197, NCIT_C124294, NCIT_C17998",
"type": "alphanumeric"
},
{
"id": "A single value or an array of orphanet terms.",
"label": "Disease or disorder",
"type": "ontology"
},
{
"id": "A single value or an array of HPO terms.",
"label": "Phenotype",
"type": "ontology"
},
{
"id": "data_2295",
"label": "Causative genes. Permitted values: any HGNC gene symbol",
"type": "alphanumeric"
},
{
"id": "NCIT_C83164",
"label": "Age this year",
"type": "numeric"
},
{
"id": "NCIT_C124353",
"label": "Symptom Onset",
"type": "numeric"
},
{
"id": "NCIT_C156420",
"label": "Age at diagnosis",
"type": "numeric"
},
{
"id": "Available Materials",
"label": "Available materials",
"type": "alphanumeric"
}
]
}
}
HTTP Request Method : GET
/map returns the information related to the list of endpoints included in this Beacon instance.
{
"meta": {
"beaconId": "BeaconAPI.cv2.rdnexusdev.molgeniscloud.org",
"apiVersion": "v2.0",
"returnedSchemas": [
{
"entityType": "individuals",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/individuals/defaultSchema.json"
},
{
"entityType": "biosamples",
"schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
}
]
},
"response": {
"$schema": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/configuration/beaconMapSchema.json",
"endpointSets": {
"Individuals": {
"entryType": "Individuals",
"rootUrl": "https://rdnexusdev.molgeniscloud.org/cv2/BeaconAPI/Individuals",
"filteringTermsUrl": "https://rdnexusdev.molgeniscloud.org/cv2/resources/beacon/filtering_terms.json"
},
"Biosamples": {
"entryType": "Biosamples",
"rootUrl": "https://rdnexusdev.molgeniscloud.org/cv2/BeaconAPI/Biosamples"
}
}
}
}
In Swagger, to query using both the /individuals endpoint & /catalogs endpoint (which are POST requests), you have to authorize the query using the Authorize button (extreme right, beside Servers dropdown in Swagger UI).
Use one of the authentication token provided to perform record level queries.
Developers Note: No matter the user agent being used to query (i.e., SwaggerUI, Postman, cURL, etc.,), the authentication header auth-key is required.