Skip to content
Docs

beacon_operations.get_beacon_map

GET
/datasets/map

Returns a map (like a web sitemap) of the different endpoints implemented in this Beacon instance.

Authorizations

  • None

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

Returning the Beacon Map.

object
schema

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
endpointSets
required

List of enpoints included in this Beacon instance. This is list is meant to inform Beacon clients, e.g. a Beacon Network, about the available endpoints, it is not used to generate any automatic list, but could be used for Beacon validation purposes.

object
>= 1 properties
key
additional properties
object
entryType
required
string
openAPIEndpointsDefinition

Reference to the file that includes the OpenAPI definition of the endpoints implemented in this Beacon instance. The referenced file MUST BE a valid OpenAPI definition file, as it is expected that the Beacon clients (e.g. a Beacon Network) should be able to parse it to discover additional details on the supported verbs, parameters, etc.

string
rootUrl
required

The base url for this entry type. Returns a list of entries. It is added here for convenience of the Beacon clients, so they don’t need to parse the OpenAPI endpoints definition to get that base endpoint. Also, in very simple Beacons, that endpoint could be the only one implemented, together with ´singleEntryUrl`, in which case the whole map of endpoints is found in the current Map.

string format: uri
singleEntryUrl

Optional, but recommended. Returns only one instance of this entry, identified by an id. It is added here for convenience of the Beacon clients, so they don’t need to parse the OpenAPI endpoints definition to get that base endpoint. Also, in very simple Beacons, that endpoint could be the only one implemented, together with ´rootUrl`, in which case the whole map of endpoints is found in the current Map.

string format: uri-template
endpoints

Optional. A list describing additional endpoints implemented by this Beacon instance for that entry type. Additional details on the endpoint parameters, supported HTTP verbs, etc. could be obtained by parsing the OpenAPI definition referenced in the openAPIEndpointsDefinition attribute.

object
key
additional properties
object
url
required

Endpoint URL

string format: uri-template
returnedEntryType
required

Which entry type is returned by querying this endpoint. It MUST match one of the entry types defined in the Beacon configuration file (beaconConfiguration.json).

string
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