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.
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.

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
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.
devices arrayoptional	The list of devices that created a service with the given identifier.
devices.[ ].deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
devices.[ ].properties optional	The properties for the given service and device combination. Will be returned when using a big enough depth parameter.
Alternative 1dictionary	The raw (compare query parameter) format, unparsed and most likely not human readable.
devices.[ ].properties. #.propId integer	The identifier of the property
devices.[ ].properties. #.tag stringconstant	A tag to differentiate between value and error properties Constant value: value
devices.[ ].properties. #.modifier object	Property related modifiers
devices.[ ].properties. #.modifier.isReadOnly boolean	Whenever or not the property is readonly.
devices.[ ].properties. #.modifier.isActionable boolean	Setting an actionable property requires the device to acknowledge and confirming the change.
devices.[ ].properties. #.modifier.isVolatile boolean	Whenever or not the property is volatile.
devices.[ ].properties. #.modifier.isError boolean	An indication that this specific property encountered an error on any operation.
devices.[ ].properties. #.modifier.isArray boolean	When set to true, the property at hand is an array rather than a single value.
devices.[ ].properties. #.type stringenum	The type of the property. Possible values: INT32, INT16, INT8, UINT32, UINT16, UINT8, FLOAT, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
devices.[ ].properties. #.value optional	The value of the property
Alternative 2dictionary	The parsed format. Keys are property names taken from the schema. If a property is not defined in the schema, the format will be 0x000:TYPE to provide at least some information.

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
deviceIdentifier 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.
services arrayoptional	The services that this specific device has created.
services.[ ].deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
services.[ ].properties optional	The properties for the given service and device combination. Will be returned when using a big enough depth parameter.
Alternative 1dictionary	The raw (compare query parameter) format, unparsed and most likely not human readable.
services.[ ].properties. #.propId integer	The identifier of the property
services.[ ].properties. #.tag stringconstant	A tag to differentiate between value and error properties Constant value: value
services.[ ].properties. #.modifier object	Property related modifiers
services.[ ].properties. #.modifier.isReadOnly boolean	Whenever or not the property is readonly.
services.[ ].properties. #.modifier.isActionable boolean	Setting an actionable property requires the device to acknowledge and confirming the change.
services.[ ].properties. #.modifier.isVolatile boolean	Whenever or not the property is volatile.
services.[ ].properties. #.modifier.isError boolean	An indication that this specific property encountered an error on any operation.
services.[ ].properties. #.modifier.isArray boolean	When set to true, the property at hand is an array rather than a single value.
services.[ ].properties. #.type stringenum	The type of the property. Possible values: INT32, INT16, INT8, UINT32, UINT16, UINT8, FLOAT, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
services.[ ].properties. #.value optional	The value of the property
Alternative 2dictionary	The parsed format. Keys are property names taken from the schema. If a property is not defined in the schema, the format will be 0x000:TYPE to provide at least some information.

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
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
properties optional	The properties for the given service and device combination. Will be returned when using a big enough depth parameter.
Alternative 1dictionary	The raw (compare query parameter) format, unparsed and most likely not human readable.
properties. #.propId integer	The identifier of the property
properties. #.tag stringconstant	A tag to differentiate between value and error properties Constant value: value
properties. #.modifier object	Property related modifiers
properties. #.modifier.isReadOnly boolean	Whenever or not the property is readonly.
properties. #.modifier.isActionable boolean	Setting an actionable property requires the device to acknowledge and confirming the change.
properties. #.modifier.isVolatile boolean	Whenever or not the property is volatile.
properties. #.modifier.isError boolean	An indication that this specific property encountered an error on any operation.
properties. #.modifier.isArray boolean	When set to true, the property at hand is an array rather than a single value.
properties. #.type stringenum	The type of the property. Possible values: INT32, INT16, INT8, UINT32, UINT16, UINT8, FLOAT, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
properties. #.value optional	The value of the property
Alternative 2dictionary	The parsed format. Keys are property names taken from the schema. If a property is not defined in the schema, the format will be 0x000:TYPE to provide at least some information.

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.

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
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
properties optional	The properties for the given service and device combination. Will be returned when using a big enough depth parameter.
Alternative 1dictionary	The raw (compare query parameter) format, unparsed and most likely not human readable.
properties. #.propId integer	The identifier of the property
properties. #.tag stringconstant	A tag to differentiate between value and error properties Constant value: value
properties. #.modifier object	Property related modifiers
properties. #.modifier.isReadOnly boolean	Whenever or not the property is readonly.
properties. #.modifier.isActionable boolean	Setting an actionable property requires the device to acknowledge and confirming the change.
properties. #.modifier.isVolatile boolean	Whenever or not the property is volatile.
properties. #.modifier.isError boolean	An indication that this specific property encountered an error on any operation.
properties. #.modifier.isArray boolean	When set to true, the property at hand is an array rather than a single value.
properties. #.type stringenum	The type of the property. Possible values: INT32, INT16, INT8, UINT32, UINT16, UINT8, FLOAT, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
properties. #.value optional	The value of the property
Alternative 2dictionary	The parsed format. Keys are property names taken from the schema. If a property is not defined in the schema, the format will be 0x000:TYPE to provide at least some information.

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.

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.

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.

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.

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.

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.

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.
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema

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.
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema

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.
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema

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.
property string	The property identifier. Either as hex 0x0000.TYPE formatted string or as the name for the property given by the schema

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.