Skip to content
Docs

beacon_operations.variants_search

POST
/g_variants

Search for variants

Authorizations

  • None

Request Body

Schema for the Beacon request.

object
meta
required

Meta section of the Beacon request. It includes request context details relevant for the Beacon server when processing the request.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
[
  "v2.0.1",
  "v0.3"
]
requestedSchemas

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
query
required

Parameters to limit the list of returned results.

object
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
pagination

Pagination to apply on the results.

object
page

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
pageSize

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
skip
  • In the request: number of pages to skip
  • In the response: number of pages that has been skipped
integer
0
filters

Filtering terms are the main means to select subsets of records from a Beacon response. While the name implies the application to a generated response, in practice implementations may apply them at the query stage. Note: In the processing of Beacon v2.0 requests multiple filters are assumed to be chained by the logical AND operator.

Array
Any of:

Filter results to include records that contain a specific ontology term.

object
id
required

Term ID to be queried, using CURIE syntax where possible.

string
HP:0002664
includeDescendantTerms

Define if the Beacon should implement the ontology hierarchy, thus query the descendant terms of id.

boolean
default: true
similarity

Allow the Beacon to return results which do not match the filter exactly, but do match to a certain degree of similarity. The Beacon defines the semantic similarity model implemented and how to apply the thresholds of ‘high’, ‘medium’ and ‘low’ similarity.

string
default: exact
Allowed values: exact high medium low
scope

The entry type in the model to which the filter should be applied. For example, the use of NCIT:C4013 (Malignant Head and Neck Neoplasm) can w/o specified scope mean both “match cancer samples” or “match individuals” with the disease” which - in the case of individuals - could then lead to matching germline and cancer variants while a scope of biosamples would limit the response to variants observed in the cancer tissue. Note: It is good practice to avoid ambiguous terms, i.e. use different vocabularies for different entry types.

string
requestParameters
object
requestedGranularity

Level of detail of the response:

  • boolean: returns true/false’ responses
  • count: adds the total number of positive results found
  • record: returns details for every row. In cases where a Beacon prefers to return records with fewer than all attributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count record

Responses

200

Successful variant search operation.

Any of:

Complete definition for a minimal response that provides only a Boolean exists true|false answer.

object
beaconHandovers

Set of handovers to be added in one section the response.

Array<object>

Requested schema to be used for individuals in the response.

object
handoverType
required

Handover type, as an Ontology_term object with CURIE syntax for the id value. Use “CUSTOM:123455” CURIE-style id when no ontology is available.

object
id
required

Definition of an identifier in the CURIE prefix:local-part format which is the default type of e.g. ontology term id values (used e.g. for filters or external identifiers).

string
/^\w[^:]+:.+$/
label

The text that describes the term. By default it could be the preferred text of the term, but is it acceptable to customize it for a clearer description and understanding of the term in an specific context.

string
key
additional properties
any
[
  {
    "id": "EDAM:2572",
    "label": "BAM"
  },
  {
    "id": "EDAM:3016",
    "label": "VCF"
  },
  {
    "id": "CUSTOM:pgxseg",
    "label": "genomic variants in .pgxseg file format"
  }
]
note

An optional text including considerations on the handover link provided.

string
This handover link provides access to a summarized VCF.
url
required

URL endpoint to where the handover process could progress, in RFC3986 format

string format: uri 
https://api.mygenomeservice.org/Handover/9dcc48d7-fc88-11e8-9110-b0c592dbf8c0/
info

Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification.

object
meta
required

Information about the response that could be relevant for the Beacon client in order to interpret the results.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
[
  "v2.0.1",
  "v0.3"
]
beaconId
required

The Id of a Beacon. Usually a reversed domain string, but any URI is acceptable. The purpose of this attribute is, in the context of a Beacon network, to disambiguate responses coming from different Beacons.

string
receivedRequestSummary
required

Section of the response that summarize the request received as it has been interpreted by the Beacon server. This summary can help to identify differences between the incoming request and its interpretation or processing, e.g. in the response granularity or pagination. The required properties include those that should be part of every request.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
[
  "v2.0.1",
  "v0.3"
]
requestedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
requestParameters
object
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
pagination

Pagination that has been applied on the results.

object
currentPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
pageSize

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
nextPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
previousPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
skip
  • In the request: number of pages to skip
  • In the response: number of pages that has been skipped
integer
0
requestedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses
  • count: adds the total number of positive results found
  • record: returns details for every row. In cases where a Beacon prefers to return records with fewer than all attributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count record
returnedGranularity

Level of detail of the response:

  • boolean: returns true/false’ responses
  • count: adds the total number of positive results found
  • record: returns details for every row. In cases where a Beacon prefers to return records with fewer than all attributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count record
returnedSchemas

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
responseSummary
required

Boolean (true/false) response section.

object
exists
required

Indicator of whether any record was observed in any of the collections queried. This should be non-null.

boolean

default

An unsuccessful operation.

object
error
required

Beacon-specific error.

object
errorCode
required

Entry not found

integer format: int32
errorMessage
string
meta
required

Information about the response that could be relevant for the Beacon client in order to interpret the results.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
[
  "v2.0.1",
  "v0.3"
]
beaconId
required

The Id of a Beacon. Usually a reversed domain string, but any URI is acceptable. The purpose of this attribute is, in the context of a Beacon network, to disambiguate responses coming from different Beacons.

string
receivedRequestSummary
required

Section of the response that summarize the request received as it has been interpreted by the Beacon server. This summary can help to identify differences between the incoming request and its interpretation or processing, e.g. in the response granularity or pagination. The required properties include those that should be part of every request.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
[
  "v2.0.1",
  "v0.3"
]
requestedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
requestParameters
object
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
pagination

Pagination that has been applied on the results.

object
currentPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
pageSize

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
nextPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
previousPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
skip
  • In the request: number of pages to skip
  • In the response: number of pages that has been skipped
integer
0
requestedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses
  • count: adds the total number of positive results found
  • record: returns details for every row. In cases where a Beacon prefers to return records with fewer than all attributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count record
returnedGranularity

Level of detail of the response:

  • boolean: returns true/false’ responses
  • count: adds the total number of positive results found
  • record: returns details for every row. In cases where a Beacon prefers to return records with fewer than all attributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count record
returnedSchemas

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string