Meta

Description

The meta module itself does two things. Firstly, it keeps track of information regarding the connection. Those are the status of the device and information about the last transmitted messages. A device is considered online when it either sends messages or answers control messages from the backend also known as pings. It is offline when no messages are being sent. If a ping message is unanswered for, the device is considered idle. Secondly, the meta module can be used to store data for each device. In this context a device is an entity that creates one or multiple services and can be identified by a unique device identifier. While services have properties that represent the state of that device, meta data should be used to add further information to this device. For example, location information or a human readable name.

Events

Following events are transmitted via the websocket.

META_STATUS_CHANGE

META_SET

META_DELETE

META_SCHEMA_ADD

META_SCHEMA_UPDATE

META_SCHEMA_DELETE

This event is sent via the websocket when meta data that was not set by a user, e.g. the key status or lastMessage, changes. Depending on the frequency of message from backend to device and vice versa this event might be seen very often. This event requires read access to the resource meta.

Name	Description
type stringconstant	Constant value: META_STATUS_CHANGE
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$
status stringenum	The status of the device. A device is considered online when it either sends messages or answers control messages from the backend also known as pings. It is offline when no messages are being sent. If a ping message is unanswered for, the device is considered idle. Possible values: online, offline, idle
lastMessage integeroptional	The UTC timestamp in milliseconds of the last message sent from the device to the backend.
lastConnect integeroptional	The UTC timestamp in milliseconds of the last connect event for the given device.
numConnects integeroptional	The number of connect attempts within the applications lifetime. This value is not persistently stored and is lost after a backend restart.
address optional
Alternative 1number
Alternative 2

API

Endpoints

GET

Get Meta Schemas

DEL

Delete all Meta Schemas

POST

Create Meta Schema

GET

Get Meta Schema

PATCH

Update a Meta Schema

DEL

Delete single Meta Schema

GET

Get Meta Data

GET

Get Device Meta Data

PUT

Set Device Meta Data

PATCH

Update Device Meta Data

DEL

Delete Device Meta Data

Get Meta Schemas

Returns a list of names for which a schema has been created. Using the query parameter depth will return the schema directly in combination with the name.

GET

/api/v1/meta/schemas

Access

This endpoint requires read permission for the resource meta.schemas.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.
lang stringoptional	A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. Pattern: ^[a-z]{2}(-[A-Z]{2})?$
untranslated booleanoptional	Whenever to return the config as is or translate specific fields

Response

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema objectoptional	The schema definition for the meta schema for the given name. Returned when the depth query parameter is used.
schema.name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.default booleanoptional	Whenever or not the schema is the default schema. The first schema will always have a default value equal to true.
schema.deviceType stringoptional	Currently, this value is unused. In future iterations of the backend the meta schema can match depending on the device type that was sent by the device. However, this type is not specified by the device in current versions.
schema.properties dictionary	The object contains the definition of properties. The key is the identifier that can, for example, be used by the alarm module to include query parameters.
schema.properties. #.name string	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.description stringoptional	An optional property description
schema.properties. #.type stringenum	Possible values: number, string, boolean, datetime
schema.properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.enum. #.description stringoptional	An optional property description
schema.properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
schema.properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
schema.properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
schema.properties. #.step numberoptional	Applicable to numeric type, this specifies the step value for the input field
schema.properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.tag booleanoptional	Whenever or not to use this meta information as a a tag
schema.properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
schema.properties. #.translations dictionaryoptional
schema.properties. #.translations. #.name stringoptional	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.translations. #.description stringoptional	An optional property description
schema.properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.translations. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
schema.properties. #.translations. #.enum. #.description stringoptional	An optional property description

Delete all Meta Schemas

Calling this endpoint will delete all meta schemas.

DELETE

/api/v1/meta/schemas

Access

This endpoint requires delete permission for the resource meta.schemas.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Create Meta Schema

Using this endpoint will create a new meta schema if not present.

POST

/api/v1/meta/schemas

Access

This endpoint requires create permission for the resource meta.schemas.

Request Body

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
default booleanoptional	Whenever or not the schema is the default schema. The first schema will always have a default value equal to true.
deviceType stringoptional	Currently, this value is unused. In future iterations of the backend the meta schema can match depending on the device type that was sent by the device. However, this type is not specified by the device in current versions.
properties dictionary	The object contains the definition of properties. The key is the identifier that can, for example, be used by the alarm module to include query parameters.
properties. #.name string	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.description stringoptional	An optional property description
properties. #.type stringenum	Possible values: number, string, boolean, datetime
properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.enum. #.description stringoptional	An optional property description
properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
properties. #.step numberoptional	Applicable to numeric type, this specifies the step value for the input field
properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.tag booleanoptional	Whenever or not to use this meta information as a a tag
properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
properties. #.translations dictionaryoptional
properties. #.translations. #.name stringoptional	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.description stringoptional	An optional property description
properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.translations. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum. #.description stringoptional	An optional property description

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get Meta Schema

Returns the meta schema for the given name

GET

/api/v1/meta/schemas/:name

Access

This endpoint requires read permission for the resource meta.schemas.

URL Parameter

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Query Parameter

Name	Description
lang stringoptional	A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. Pattern: ^[a-z]{2}(-[A-Z]{2})?$
untranslated booleanoptional	Whenever to return the config as is or translate specific fields

Response

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
default booleanoptional	Whenever or not the schema is the default schema. The first schema will always have a default value equal to true.
deviceType stringoptional	Currently, this value is unused. In future iterations of the backend the meta schema can match depending on the device type that was sent by the device. However, this type is not specified by the device in current versions.
properties dictionary	The object contains the definition of properties. The key is the identifier that can, for example, be used by the alarm module to include query parameters.
properties. #.name string	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.description stringoptional	An optional property description
properties. #.type stringenum	Possible values: number, string, boolean, datetime
properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.enum. #.description stringoptional	An optional property description
properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
properties. #.step numberoptional	Applicable to numeric type, this specifies the step value for the input field
properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.tag booleanoptional	Whenever or not to use this meta information as a a tag
properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
properties. #.translations dictionaryoptional
properties. #.translations. #.name stringoptional	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.description stringoptional	An optional property description
properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.translations. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum. #.description stringoptional	An optional property description

Update a Meta Schema

This endpoint can be used by sending a partial service definition. This definition will be merged with the current one. Duplicate keys will be overwritten.

PATCH

/api/v1/meta/schemas/:name

Access

This endpoint requires update permission for the resource meta.schemas.

URL Parameter

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Request Body

Name	Description
name stringoptional	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
default booleanoptional	Whenever or not the schema is the default schema. The first schema will always have a default value equal to true.
deviceType stringoptional	Currently, this value is unused. In future iterations of the backend the meta schema can match depending on the device type that was sent by the device. However, this type is not specified by the device in current versions.
properties dictionaryoptional	The object contains the definition of properties. The key is the identifier that can, for example, be used by the alarm module to include query parameters.
properties. #.name stringoptional	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.description stringoptional	An optional property description
properties. #.type stringoptionalenum	Possible values: number, string, boolean, datetime
properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.enum. #.description stringoptional	An optional property description
properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
properties. #.step numberoptional	Applicable to numeric type, this specifies the step value for the input field
properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.tag booleanoptional	Whenever or not to use this meta information as a a tag
properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
properties. #.translations dictionaryoptional
properties. #.translations. #.name stringoptional	The property name Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.description stringoptional	An optional property description
properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.translations. #.enum. #.name string	Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$
properties. #.translations. #.enum. #.description stringoptional	An optional property description

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete single Meta Schema

Delete a single given schema.

DELETE

/api/v1/meta/schemas/:name

Access

This endpoint requires delete permission for the resource meta.schemas.

URL Parameter

Name	Description
name string	The name of the schema to differentiate between schemas. Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get Meta Data

Returns a list of devices that offer meta data. If the optional depth query parameter is used, the return value contains all known meta information for each device.

GET

/api/v1/meta

Access

This endpoint requires read permission for the resource meta.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$
metaInformation objectoptional	An object to collect any relevant meta information regarding a device. Such as any meta data set by the user and connection information that belong to a device rather than a service.
metaInformation.status stringenum	The status of the device. A device is considered online when it either sends messages or answers control messages from the backend also known as pings. It is offline when no messages are being sent. If a ping message is unanswered for, the device is considered idle. Possible values: online, offline, idle
metaInformation.lastMessage integeroptional	The UTC timestamp in milliseconds of the last message sent from the device to the backend.
metaInformation.lastConnect integeroptional	The UTC timestamp in milliseconds of the last connect event for the given device.
metaInformation.numConnects integeroptional	The number of connect attempts within the applications lifetime. This value is not persistently stored and is lost after a backend restart.
metaInformation.data dictionaryoptional	An object that allows key-value storage. The keys are strings while the values can be of any type. This object holds the data that has been set by a user for that given device.
metaInformation.address optional
Alternative 1number
Alternative 2

Get Device Meta Data

Returns the meta data for a single device.

GET

/api/v1/meta/:deviceIdentifier

Access

This endpoint requires read permission for the resource meta.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Response

Name	Description
status stringenum	The status of the device. A device is considered online when it either sends messages or answers control messages from the backend also known as pings. It is offline when no messages are being sent. If a ping message is unanswered for, the device is considered idle. Possible values: online, offline, idle
lastMessage integeroptional	The UTC timestamp in milliseconds of the last message sent from the device to the backend.
lastConnect integeroptional	The UTC timestamp in milliseconds of the last connect event for the given device.
numConnects integeroptional	The number of connect attempts within the applications lifetime. This value is not persistently stored and is lost after a backend restart.
data dictionaryoptional	An object that allows key-value storage. The keys are strings while the values can be of any type. This object holds the data that has been set by a user for that given device.
address optional
Alternative 1number
Alternative 2

Set Device Meta Data

This endpoint will store the request body in the data field of the given device and furthermore overwrite any currently stored meta data. Sending an empty object will delete the meta data.

PUT

/api/v1/meta/:deviceIdentifier

Access

This endpoint requires update permission for the resource meta.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Request Body

The body of the request will be set as the meta data for the device. Any current meta will be overwritten. The request body should be in the json format.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Update Device Meta Data

Merge the request body with any present meta data for the given device. This operation will overwrite any existing keys with new values if a key is present in the current meta data as well as in the request body.

TIP

In order to delete a single key set its value to __DELETE and it will be removed.

PATCH

/api/v1/meta/:deviceIdentifier

Access

This endpoint requires update permission for the resource meta.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Request Body

The body of the request will be merged with the current meta data for the device. The request body should be in the json format.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete Device Meta Data

Calling this endpoint will delete the meta data for the given device.

DELETE

/api/v1/meta/:deviceIdentifier

Access

This endpoint requires delete permission for the resource meta.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.