Skip to content
Docs

beacon_operations.get_beacon_info_root

GET
/datasets/info

Get information about the beacon

Authorizations

  • None

Parameters

Query Parameters

requestedSchema
string

Schema to be used to format the result field in the resposne. The response will use Beacon format.

Example
ga4gh-service-info-v1.0

Responses

200

Successful operation

Response of a request for information about a Beacon

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

Metadata describing a Beacon instance.

object
id
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
name
required

Name of the Beacon.

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"
]
environment
required

Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments.

string
Allowed values: prod test dev staging 
[
  "dev"
]
organization
required

Organization owning the Beacon.

object
id
required

Unique identifier of the organization.

string
name
required

Name of the organization.

string
description

Description of the organization.

string
address

Address of the organization.

string
welcomeUrl

URL of the website of the organization (RFC 3986 format).

string
contactUrl

URL with the contact for the Beacon operator/maintainer, e.g. link to a contact form (RFC 3986 format) or an email (RFC 2368 format).

string
logoUrl

URL to the logo (PNG/JPG/SVG format) of the organization (RFC 3986 format).

string
info

Additional unspecified metadata about the host Organization.

object
description

Description of the Beacon.

string
version

TODO: This is a legacy use / duplication?

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

URL to the welcome page for this Beacon (RFC 3986 format).

string
https://example.org/wiki/Main_Page
alternativeUrl

Alternative URL to the API, e.g. a restricted version of this Beacon (RFC 3986 format).

string
[
  "https://example.org/beacon/authenticated"
]
createDateTime

The date/time the Beacon was created (ISO 8601 format).

string
[
  "2014-07-19",
  "2017-01-17T20:33:40Z"
]
updateDateTime

The time the Beacon was updated in (ISO 8601 format).

string
[
  "2014-07-19",
  "2017-01-17T20:33:40Z"
]
info

Additional unspecified metadata about the Beacon service.

object
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