Skip to content

API: Beacon Responses

The following is a list of standard Beacon responses supported by the bycon package. Responses for individual entities or endpoints are grouped by their Beacon framework response classes (e.g. beaconResultsetsResponse for biosamples, g_variants etc.).\n\n Please be reminded about the general syntax used in Beacon: A path element such as /biosamples corresponds to an entity (here biosample). Below these relations are indicated by the @ symbol.\n\n

API Parameters

A complete list of parameters accepted by the API is provided on the Web and Command Line Parameters page.

Schemas {S}, Tests {T} and Examples {E}

Tests, examples and schemas are run from the server defined in this site's build instructions (see the current progenetix.org entry for reference_server_url entry in the github.com/progenetix/bycon/blob/main/mkdocs.yaml configuration file.

beaconCollectionsResponse

A type of Beacon response that includes details about the collections in a beacon. The types of collections are defined in each beacon's configuration; if using the Beacon v2+ default model usually the types dataset and cohort are supported.

dataset @ /datasets

A dataset available in the beacon.

cohort @ /cohorts

A cohort available in the beacon.

beaconInfoResponse

The beaconInfoResponse provides metadata describing a Beacon instance, such as its name, the organization responsible for the Beacon, contact information, site logo and alternative URLs and importantly the beacon's API version. It is based on the GA4GH service-info standard. The content of the beaconInfoResponse can be used by clients such as web front ends or beacon aggregators to evaluate potential access patterns and to display information about the beacon.

info @ /info

Metadata describing a Beacon instance.

beaconConfigurationResponse

The beaconConfigurationResponse returns information about configuration parameters of a given beacon instance such as maturity or security attributes or supported entry types. It is directed towards Beacon clients like web pages or network aggregators.

configuration @ /configuration

The Beacon configuration reports several attributes of the beacon instance related to security, maturity and available entry types. Where appropriate the details returned in service-info should mirror the ones in this configuration.

beaconBooleanResponse

Complete definition for a minimal response that provides only an aggregate Boolean "exists": true or "exists": false answer to the query.
Additional information - which should not consist of record-level information - can be provided through beaconHandovers.

For a list of entities potentially served by beaconBooleanResponse depending on the selected or granted responseGranularity please check beaconResultsetsResponse.

beaconFilteringTermsResponse

The filtering terms response provides information about available individual filters for a beacon's entry types as well as optional information about the ontologies the filters belong to.

filteringTerm @ /filtering_terms

Schema for the Filtering Terms list related to the hosting entry type. It is kept separated to allow updating it independently.

beaconErrorResponse

A beaconErrorResponse denotes an unsuccessful operation, e.g. due to a missing parameter or an invalid query. The response contains an error object.

beaconMapResponse

A beaconMapResponse provides information about the beacon instance such as the different endpoints supported by this implementation of the Beacon API. This response is aimed to allow Beacon clients such as web front ends and Beacon network aggregators to evaluate which access patterns can be implemented against individual beacons.

beaconMap @ /map

Map of a Beacon, its entry types and endpoints. It isconceptually similar to a website sitemap.

beaconResultsetsResponse

A beaconResultsetsResponse returns the results of a query against a beacon or beacon aggregator. Beyond the responseSummary for overall matches the response contains details about the matches in individual collections in the beacon or beacon network. This type of response is required when serving a request with a "record" level responseGranularity, and beaconResultsets typically contain a list of records matched by the query. The types of beaconResultsets objects are defined in the beacon's configuration; e.g. if using the Beacon v2+ default model the types dataset and cohort are supported as result sets.

genomicVariant @ /g_variants

The type of response used for the endpoint depends on the requested and granted responseGranularity.

analysis @ /analyses

The analysis schema represents a information about the data analysis steps leading to (a set of) genomic variation call(s).

The type of response used for the endpoint depends on the requested and granted responseGranularity.

run @ /runs

Schema for the experimental run (e.g. sequencing run, array processing...) leading to the raw data for the (computational) analysis. NOTE: In the bycon environment run parameters are stored in the analysis documents and rewritten into this schema at export time.

The type of response used for the endpoint depends on the requested and granted responseGranularity.

biosample @ /biosamples

A Biosample refers to a unit of biological material from which the substrate molecules (e.g. genomic DNA, RNA, proteins) for molecular analyses (e.g. sequencing, array hybridisation, mass-spectrometry) are extracted. Examples would be a tissue biopsy, a single cell from a culture for single cell genome sequencing or a protein fraction from a gradient centrifugation. Several instances (e.g. technical replicates) or types of experiments (e.g. genomic array as well as RNA-seq experiments) may refer to the same Biosample.

The type of response used for the endpoint depends on the requested and granted responseGranularity.

individual @ /individuals

None

The type of response used for the endpoint depends on the requested and granted responseGranularity.

phenopacket @ /phenopackets

The Phenopacket class is a bare-bones JSON-schema rewrite of the Phenopackets v2 standard ("PXF"), for the representation of attributes supported in the bycon framework. At this time the Phenopackets schema is not part of the Beacon v2 default data model. However, many sub-schemas in Beacon v2 have been informed by the PXF model and development process, allowing a straightforward cross-mapping of the data structures.

The type of response used for the endpoint depends on the requested and granted responseGranularity. In the bycon framework Phenopackets are generated at export time by aggregating the relevant information from the matched individual, biosamples, analysis(/es) and genomicVariations.

beaconEntryTypesResponse

The beaconEntryTypesResponse provides information about the entry types served through a beacon, including their definitions and pointers to their schemas.

entryType @ /entry_types

Schema for the entry types list.

beaconCountResponse

Complete definition for a minimal response that provides an aggregate Boolean "exists": true or "exists": false answer to the query as well as the count of the matched records. Additional information - which should not consist of record-level information - can be provided through beaconHandovers.

For a list of entities potentially served by beaconBooleanResponse depending on the selected or granted responseGranularity please check beaconResultsetsResponse.