Service

Description

The service module offers an insight into the current state of the devices. It offers multiple API endpoints to check what services devices created and what properties those services have and what their current value is. Furthermore, with this API it is possible to set properties on any device service directly.

Events

Following events are transmitted via the websocket.

OBJECT_UPDATED

This event will be fired when an object updates any of its properties. This event requires read access to the resource service.

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=-]+)$
flakeAddress integer	The flake address for the given action. This value is the address the device is available at internally. The value might be removed from the event since it offers no real value for developers.
timestamp integer	The timestamp of event.
type stringconstant	Constant value: OBJECT_UPDATED
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
identifier stringoptional	The optional identifier when using multiple services.
updates array	A list of property updates. Each property can be a tagged as either a value-update (successful change) or an error property.
discoveryAction booleanoptional	Whether this action was triggered during device discovery.

API

Endpoints

GET

Get Service List

GET

Get Device List

GET

Get Devices for a given Service

GET

Get Services for a given Device

GET

Get Properties

GET

Get Properties

PUT

Update Properties

PUT

Update Properties

PUT

Call Custom Message

PUT

Call Custom Message

GET

Read Open Property

GET

Read Open Property

PUT

Write Open Property

PUT

Write Open Property

Get Service List

Returns a list of all known services.

GET

/api/v1/services

Access

This endpoint requires read permission for the resource service.

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Get Device List

Returns a list of all known devices.

GET

/api/v1/devices

Access

This endpoint requires read permission for the resource service.

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Get Devices for a given Service

Returns a list of all devices that have created a specific service.

GET

/api/v1/services/:serviceIdentifier/devices

Access

This endpoint requires read permission for the resource service.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Get Services for a given Device

Returns a list of all services that have a been created by a given device.

GET

/api/v1/devices/:deviceIdentifier/services

Access

This endpoint requires read permission for the resource service.

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=-]+)$

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Get Properties

Returns the properties for a given service device combination.

GET

/api/v1/services/:serviceIdentifier/devices/:deviceIdentifier

Access

This endpoint requires read permission for the resource service.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Get Properties

Returns the properties for a given device service combination.

GET

/api/v1/devices/:deviceIdentifier/services/:serviceIdentifier

Access

This endpoint requires read permission for the resource service.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$

Query Parameter

Name	Description
raw booleanoptional	Whenever to return the raw property format or the human readable format. Defaults to false.
hex booleanoptional	Whenever or not to return the property IDs in the hex format rather than the decimal format.
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

Update Properties

Changes the properties of the device.

PUT

/api/v1/services/:serviceIdentifier/devices/:deviceIdentifier

Access

This endpoint requires update permission for the resource service.properties.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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

Name	Description

Response

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

Update Properties

Changes the properties of the device.

PUT

/api/v1/devices/:deviceIdentifier/services/:serviceIdentifier

Access

This endpoint requires update permission for the resource service.properties.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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

Name	Description

Response

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

Call Custom Message

Runs a custom message if available on the device.

PUT

/api/v1/services/:serviceIdentifier/devices/:deviceIdentifier/customMessage/:customMessage

Access

This endpoint requires update permission for the resource service.customMessage.

URL Parameter

Name	Description
customMessage string	The name of the custom message.
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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

Name	Description

Response

Name	Description

Call Custom Message

Runs a custom message if available on the device.

PUT

/api/v1/devices/:deviceIdentifier/services/:serviceIdentifier/customMessage/:customMessage

Access

This endpoint requires update permission for the resource service.customMessage.

URL Parameter

Name	Description
customMessage string	The name of the custom message.
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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

Name	Description

Response

Name	Description

Read Open Property

Retrieves the open property and returns it as a whole

GET

/api/v1/services/:serviceIdentifier/devices/:deviceIdentifier/openProperty/:property

Access

This endpoint requires read permission for the resource service.openProperty.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Query Parameter

Name	Description
retries integeroptional	The number of retries within a open property read or write request. Default: 5

Response

Name	Description
data	The data of the requested open property. Either as string or buffer-object.
Alternative 1string
Alternative 2object	A representation of a buffer. The buffer can also be sent as a base64 encoded string.
data.type stringconstant	Constant value: Buffer
data.data array

Read Open Property

Retrieves the open property and returns it as a whole

GET

/api/v1/devices/:deviceIdentifier/services/:serviceIdentifier/openProperty/:property

Access

This endpoint requires read permission for the resource service.openProperty.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Query Parameter

Name	Description
retries integeroptional	The number of retries within a open property read or write request. Default: 5

Response

Name	Description
data	The data of the requested open property. Either as string or buffer-object.
Alternative 1string
Alternative 2object	A representation of a buffer. The buffer can also be sent as a base64 encoded string.
data.type stringconstant	Constant value: Buffer
data.data array

Write Open Property

Writes the contents to the stream. Each transmission has at most 400 bytes

PUT

/api/v1/services/:serviceIdentifier/devices/:deviceIdentifier/openProperty/:property

Access

This endpoint requires update permission for the resource service.openProperty.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Request Body

Name	Description
data	The data of the requested open property. Either as string or buffer-object.
Alternative 1string
Alternative 2object	A representation of a buffer. The buffer can also be sent as a base64 encoded string.
data.type stringconstant	Constant value: Buffer
data.data array

Response

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

Write Open Property

Writes the contents to the stream. Each transmission has at most 400 bytes

PUT

/api/v1/devices/:deviceIdentifier/services/:serviceIdentifier/openProperty/:property

Access

This endpoint requires update permission for the resource service.openProperty.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
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=-]+)$
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema Pattern: ^[0-9a-zA-Z\p{Letter}\p{Mark}\-._\s ]+$

Request Body

Name	Description
data	The data of the requested open property. Either as string or buffer-object.
Alternative 1string
Alternative 2object	A representation of a buffer. The buffer can also be sent as a base64 encoded string.
data.type stringconstant	Constant value: Buffer
data.data array

Response

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