The JSON-LD context

GET

/gateway/{alias}/v1/context.jsonld

const url = 'https://example.com/gateway/example/v1/context.jsonld';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/gateway/example/v1/context.jsonld \
  --header 'Authorization: Bearer <token>'

Maps the plain JSON keys of the messages onto Brick, QUDT and Buildinglinks terms; published at https://w3id.org/buildinglinks/v1/context.jsonld.

Authorizations

Parameters

Path Parameters

alias

required

string

The connection (abonnement) to call through, as Verbindingen in the connector names it.

Responses

200

The context.

401

From the backend: unauthenticated: no or a wrong key. From the gateway: unauthenticated: no key, an unknown key, or an invalid token of the control plane.

application/json

Any of:

ErrorResponse
object

ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object

buildinglinks_version

required

Protocol version, carried by every response.

string

/^1\.[0-9]+$/

building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string

>= 1 characters

error

required

object

code

required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string

message

required

string

retryable

required

boolean

target

Which field caused it, for example setpoints[0].value.

string

retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string

/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/

details

Array<object> recursive

Example

{
  "error": {
    "code": "invalid_request"
  }
}

403

forbidden: the key lacks the gateway scope, its app may not use this connection, or the app may only read. The provider’s data plane refuses with 403 what the agreement does not cover.

application/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}

502

upstream_unavailable: the provider’s data plane could not be reached, its answer was larger than 16 MiB, or, when the agreement requires signed requests, its answer had no valid signature.

application/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}

503

upstream_unavailable: the connection is not active (yet), or renewing the access token failed; evidence_unavailable: the agreement requires signed requests and the request or answer could not be recorded; standby: another instance of this data plane is active. Retryable.

application/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}