WARNING !!!

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.

REST API specification for querying RD resources (Virtual Platform Level 2)

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.

---

Contents

• Try out this API in Swagger
• Specification
• Query Endpoints
  • Individuals endpoint
    • List of filters
    • Filters description
    • Example request & response
  • Biosamples endpoint
    • List of filters
    • Filters description
    • Example request & response
  • Catalogs endpoint
    • List of filters
    • Filters description
    • Example request & response
• Authentication using Header(s)
• Understanding the query
  • Syntax & Usage of Beacon Query with Filters
    • Multi-Filter (AND) query
    • Same Filter (AND) query
    • Multi-Filter (OR) query using Arrays
  • Partial query matches with warning messages
• Understanding the response with ranges (for /individuals and /biospecimens)
• Informational Endpoints

---

Try out the API

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#/

---

Specification

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.

---

Query Endpoints ( Mandatory to implement atleast one of the query endpoints)

This specification defines POST endpoints to request information about resources. Each endpoint makes use of the Filters capability of the Beacon API.

Individuals endpoint

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.

List of filters and permitted values for the individuals endpoint

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

^ Back to the top

---

Individuals Filters Description

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.

^ Back to the top

---

Example request and response for individuals

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
            }
        ]
    }
}

Biosamples endpoint

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.

List of filters and permitted values for the biosamples endpoint

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

^ Back to the top

---

Biosamples Filters Description

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

^ Back to the top

---

Example request and response for biosamples

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

^ Back to the top

---

Catalogs endpoint

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

List of filters and permitted values for the catalogs endpoint

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

^ Back to the top

---

Catalogs Filters Description

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.

^ Back to the top

---

Catalogs Response

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 request and response for catalogs

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

^ Back to the top

---

Authentication using Header

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.

^ Back to the top

---

Understanding the query

Syntax and Usage:

Method: POST

There are 3 types of Beacon queries that this specification currently supports:

1. Alphanumerical Query
2. Numerical Query
3. Ontology Query

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"
  }
}

^ Back to the top

---

As shown above, different types of filters can be sent in a single query. These are further elucidated below.

Beacon queries using multiple filters (AND logical operator between filters):

{
"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.

^ Back to the top

---

Beacon queries using multiples of the same type of filter (AND logical operator between filters):

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.

^ Back to the top

---

Beacon queries using multiples of the same type of filter (OR logical operator between filters):

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.

^ Back to the top

---

Partial Request & Response with warning message Example

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.

^ Back to the top

---

Understanding the response with ranges (for /individuals and /biospecimens)

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).

^ Back to the top

---

Informational Endpoints (Mandatory to be implemented for all the resources )

This specification defines GET endpoints to request information about resources.

Info endpoint

HTTP Request Method : GET

/info returns the information about the Beacon.

Example response for info

{
    "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/"
    }
}

Service-info endpoint

HTTP Request Method : GET

/service-info returns the information about the basic metadata concerning its service, based on the reference specification.

Example response for service-info

{
    "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"
}

Configuration

HTTP Request Method : GET

/configuration returns the information about the Beacon.

Example response for service-info

{
    "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"
        }
    }
}

Entry-types

HTTP Request Method : GET

/entry-types returns the information about the Beacon.

Example response for entry-types

{
    "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"
                }
            }
        }
    }
}

Filtering_terms

HTTP Request Method : GET

/filtering_terms returns the information about the Beacon.

Example response for filtering_terms

{
    "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"
            }
        ]
    }
}

Map

HTTP Request Method : GET

/map returns the information related to the list of endpoints included in this Beacon instance.

Example response for map

{
    "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"
            }
        }
    }
}

^ Back to the top

---

Authentication using Header for Swagger

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.

^ Back to the top

---