Device Registration API

NB: THIS IS A FIRST DRAFT VERSION OF THE API SPEC AND THUS STILL SUBJECT TO DISCUSSION. IF YOU THINK THAT THE SPEC SHOULD BE CHANGED OR CAN BE IMPROVED PLEASE DO NOT HESITATE TO OPEN AN ISSUE OR DROP US A LINE ON THE MAILING LIST.

The Device Registration API is used to make Hono aware of devices that will connect to the service and send telemetry data. It can be used by Protocol Adapters to register devices that are not directly connected to Hono using an AMQP 1.0 connection. Solutions and other consumers may use the API to obtain information about a single device that is registered to Hono. (tbd??)

The Device Registration API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.

Use Cases

The following diagram provides an overview of the device registration related use cases Hono supports.

TODO add use case diagram

Operations

The following operations can be used by Protocol Adapters to register devices.

Register/Deregister device

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role sender with Hono using target address registration.
3. Client has established an AMQP link in role receiver with Hono using source address registration?

Message Flow

TODO add sequence diagram

Message Format

The following table provides an overview of the properties a client needs to set on an Device Registration message.

Name	Mandatory	Location	Type	Description
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
tenant-id	no	application-properties	UTF-8 string	MAY be set by the client to indicate which tenant the device belongs to.
action/to	yes	application-properties	UTF-8 string	MUST contain the action (add/remove) that should be executed.
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID used to send a reply to this message.

The body of the message is empty.

AMQP message delivery states are used as follows:

Delivery State	Description
ACCEPTED	Indicates that Hono has successfully received and accepted the message for processing.
REJECTED	Indicates that Hono has received the message but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the message using the same message properties in this case.

Response

Name	Mandatory	Location	Type	Description
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
tenant-id	yes	application-properties	UTF-8 string	MUST contain the tenant to which the device belongs to.
status	yes	application-properties	int	MUST contain the status code indicating the result of the operation.
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID of the incoming message.

Dependent on the status code the message body is empty (success) or contains a detailed description of the error that occurred (error format tbd.).

Retrieve information about a registered device

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role sender with Hono using target address registration.
3. Client has established an AMQP link in role receiver with Hono using source address registration?

Message Flow

TODO add sequence diagram

Message Format

The following table provides an overview of the properties a client needs to set on a message to retrieve a registered device.

Name	Mandatory	Location	Type	Description
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device to be queried.
tenant-id	no	application-properties	UTF-8 string	MAY be set by the client to indicate which tenant the device belongs to.
action/to	yes	application-properties	UTF-8 string	MUST contain the action get.
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID used to send a reply to this message.

The message body is empty.

AMQP message delivery states are used as follows:

Delivery State	Description
ACCEPTED	Indicates that Hono has successfully received and has accepted the message for processing.
REJECTED	Indicates that Hono has received the message but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the message using the same message properties in this case.

Response

The client receives a response with status success if the device with the given device-id is registered or failure if the device-id is unknown to Hono.

Name	Mandatory	Location	Type	Description
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
tenant-id	yes	application-properties	UTF-8 string	MUST contain the tenant to which the device belongs to.
status	yes	properties	int	MUST contain the status code indicating the result of the operation. 0 for success i.e. the device is registered, 1 for failure i.e was not found or the user has no permission to see it.
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID of the incoming message.

The message body is empty.