Ga naar inhoud
buildinglinksbuildinglinks

Get the layout of the building

GET
/gateway/{alias}/v1/buildings/{building_id}/topology
curl --request GET \
  --url https://example.com/gateway/example/v1/buildings/example/topology \
  --header 'Authorization: Bearer <token>'

The locations of the building and where each point is (profile https://w3id.org/buildinglinks/v1/topology). A backend may serve only this operation: a topology source, such as an installer’s BIM model.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
alias
required
string

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

building_id
required

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

string
>= 1 characters

The object id of the building: its register identification in dotted form, e.g. nl.bag.pand.0014100040022681.

Query Parameters

Section titled “Query Parameters”
point_ids
string

Only these points, and only the locations they are in with everything above them. A comma-separated list (a,b) or the parameter repeated; at least one id.

Responses

Section titled “Responses”

200

Section titled “200”

The layout.

Media typeapplication/json
TopologyResponse

Response of GET /v1/buildings/{building_id}/topology (profile https://w3id.org/buildinglinks/v1/topology, decision #71): the locations of the building and where each point is. Point ids are those of the source. With point_ids only those points, and only the locations they are in with everything above them (part_of).

object
buildinglinks_version
required

Protocol version, carried by every response.

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

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

string
>= 1 characters
locations
required
Array<object>
Location

V2 draft: a place in the building (the building, a level, a room or a zone). Classes come from RealEstateCore, for example rec:Building, rec:Level, rec:Room, rec:Zone and rec:HVACZone.

object
location_id
required

Id of a location returned with include=locations (v2 draft).

string
>= 1 characters
name
required
string
class
required

RealEstateCore (rec:) or Brick location class.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
part_of

The enclosing location; absent for the building itself.

string
>= 1 characters
points
required
Array<object>
object
point_id
required

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
location_id
required

Id of a location returned with include=locations (v2 draft).

string
>= 1 characters

Example generated

{
  "buildinglinks_version": "example",
  "building_id": "example",
  "locations": [
    {
      "location_id": "example",
      "name": "example",
      "class": "example",
      "part_of": "example"
    }
  ],
  "points": [
    {
      "point_id": "example",
      "location_id": "example"
    }
  ]
}

400

Section titled “400”

invalid_request, or a write the backend refuses as a whole (point_not_writable, value_out_of_range, …).

Media typeapplication/json
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"
  }
}

401

Section titled “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.

Media typeapplication/json
Any of:
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

Section titled “403”

From the backend: forbidden: the key may not use this building. From the gateway: 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.

Media typeapplication/json
Any of:
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"
  }
}

404

Section titled “404”

building_not_found, or not_found for an unknown route.

Media typeapplication/json
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"
  }
}

502

Section titled “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.

Media typeapplication/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

Section titled “503”

From the backend: upstream_unavailable: the building’s systems cannot be reached; retryable. From the gateway: 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.

Media typeapplication/json
Any of:
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"
  }
}