This API specifications are defined in the context of the EJPRD project.
In this work we present API specifications 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.
Method : POST
/individuals endpoint returns the count of individuals from a RD resource. This endpoint specification is drafted based on beacon-v2 API specification. The request can also contain filters which are CDE based filter parameters to filter individuals. These filters are provided as a part of request body. An example filters json is shown below.
{
"query": {
"description": "Query to get count of female (obo:NCIT_C16576) individuals with diagnostic opinion (sio:SIO_001003) marfan syndrome (ordo:Orphanet_558)",
"filters": [
{
"type": "obo:NCIT_C28421",
"id": "obo:NCIT_C16576",
"operator": "="
},
{
"type": "sio:SIO_001003",
"id": "ordo:Orphanet_558",
"operator": "="
}
]
}
}| Filter name | Type term | Permitted values |
|---|---|---|
| Sex | obo:NCIT_C28421 | obo:NCIT_C16576 |
| obo:NCIT_C20197 | ||
| obo:NCIT_C124294 | ||
| obo:NCIT_C17998 | ||
| Diagnosis of the rare disease |
sio:SIO_001003 | Any orphanet term. e.g. ordo:Orphanet_558 |
| Phenotype | sio:SIO_010056 | Any hpo term. e.g. obo:HP_0001251 |
| Causative genes | obo:NCIT_C16612 | any HGNC gene symbol |
| Age this year | obo:NCIT_C25150 | any integer |
| Age at disease manifestation | efo:EFO_0004847 | any integer |
| Age at diagnosis | obo:NCIT_C156420 | any integer |
| Available materials | Whole Genome Sequence | |
| Whole Exome Sequence | ||
| Exome panel sequence | ||
| RNA sequence | ||
| methylomics | ||
| Epigenomics | ||
| Pedigree data | ||
| Clinical data | ||
| Biosamples |
All filters are to be handled independently, see below example for clarification.
{
"query": {
"filters": [
{
"type": "sio:SIO_001003",
"id": "ordo:Orphanet_34587",
"operator": "="
},
{
"type": "obo:NCIT_C16612",
"id": "LAMP2",
"operator": "="
}
]
}
}This filter is asking for individuals which 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.
| Filter | Filter description | Filter interpretation |
|---|---|---|
| Sex | The biological sex of the patient | |
| Diagnosis of the rare disease |
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. | To be handled independently of other filters |
| Phenotypes observed | HPO terms of all phenotypes observed within an individual | To be handled independently of other filters |
| Causative genes | All genes which have been deemed as causative of one or more of the diagnosed rare diseased, encompassing and not distinguishing between all certainty levels of causality | To be handled independently of other filters |
| Age this year | Age at the end of the current year | -/+ 1 will be added to all age queries when executed by the query engine at the resource |
| Age at disease manifestation |
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. -/+ 1 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 diagnosis independently. -/+ 1 will be added to all age queries when executed by the query engine at the resource |
| Available materials | A list of what information is available about an individual |
Beacon queries require the use of the AND logical operator between filters and each filter can have at most one possible value.
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:
{
"query": {
"filters": [
{
"type": "sio:SIO_001003",
"id": "ordo:Orphanet_34587",
"operator": "="
},
{
"type": "sio:SIO_001003",
"id": "ordo:Orphanet_1653",
"operator": "="
}
]
}
}This query is looking for individuals with Danon disease ("ordo:Orphanet_34587") AND Dentin dysplasia ("ordo:Orphanet_1653").
There are no OR operators available 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.
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.
An example request which can be sent to a resource is shown below:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"meta":{},
"query":{
"requestParameters": [],
"filters": [
{
"type": "sio:SIO_001003",
"id": "ordo:Orphanet_34587",
"operator": "="
},
{
"type": "obo:NCIT_C16612",
"id": "LAMP2",
"operator": "="
},
{
"type": "obo:NCIT_C28421",
"id": "obo:NCIT_C16576",
"operator": "="
}
]
}
}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:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"meta": {},
"responseSummary":{
"exists": "true",
"numTotalResults": 10
},
"info": {
"warnings":{
"unsupportedFilters": [
"obo:NCIT_C16612"
]
}
}
}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.
-
The Swagger Software offers several free tools that help build APIs that are compliant with the OpenAPI specification:
- Swagger Editor can be used to build valid API calls.
- Swagger Inspector is a browser extension that can be used to validate API calls.