Skip to content
Docs

beacon_operations.get_beacon_configuration

GET
/datasets/configuration

Returns some configuration aspects and the definition of the entry types (e.g. genomic variants, biosamples, cohorts, individuals and runs) implemented in this specific Beacon server or instance.

Authorizations

  • None

Responses

200

Successful operation.

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.

object
meta
required

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

object
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
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"
]
returnedSchemas
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
key
additional properties
any
response
required

Returning the Beacon configuration.

object
$schema
required

Refers to the JSON Schema which describes the set of valid attributes for this particular document type. This attribute is mostly used in schemas that should be tested in Beacon implementations.

string
maturityAttributes
required

Declares the level of maturity of the Beacon instance.

object
productionStatus
  • DEV: Service potentially unstable, i.e. potentially not real data, inconsistent availability; data should not be used in production setups
  • TEST: Service is stable but data should be considered synthetic * PROD: Service stable with real world data
string
Allowed values: DEV TEST PROD
securityAttributes

Configuration of the security aspects of the Beacon. By default, a Beacon that does not declare the configuration settings would return boolean (true/false) responses, and only if the user is authenticated and explicitly authorized to access the Beacon resources. Although this is the safest set of settings, it is not recommended unless the Beacon shares very sensitive information. Non sensitive Beacons should preferably opt for a record and PUBLIC combination.

object
defaultGranularity

Default granularity. Some responses could return higher detail, but this would be the granularity by default.

string
default: boolean
Allowed values: boolean count record
securityLevels

All access levels supported by the Beacon. Any combination is valid, as every option would apply to different parts of the Beacon.

Array
default: CONTROLLED
Allowed values: PUBLIC REGISTERED CONTROLLED
entryTypes
required

This is a dictionary of the entry types implemented in this Beacon instance.

key
additional properties
any
key
additional properties
any

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