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.

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.

Operations

The following operations can be used by clients to register devices. In real world scenarios the provisioning of devices will most likely be an orchestrated process spanning multiple components of which Hono will only be one. Conducting and orchestrating the overall provisioning process is not in scope of Hono. However, Hono's device registration API can easily be used as part of such an overall provisioning process.

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/${tenant_id}.
3. Client has established an AMQP link in role receiver with Hono using source address registration/${tenant_id}/${reply-id} (where reply-id can be any random id).

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
message-id	yes	properties	UTF-8 string	MUST contain the message ID used to match incoming message with the response message containing result of execution.
reply-to	yes	properties	UTF-8 string	MUST contain the address where replies are sent to.
correlation-id	no	properties	UTF-8 string	MAY contain an ID used to correlate the response to the original request. If the correlation-id is set it is used as the correlation-id property in the response otherwise the message-id is used.
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
action	yes	application-properties	UTF-8 string	MUST contain the action that should be executed (register or deregister).

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
correlation-id	yes	properties	UTF-8 string	MUST contain the message-id (or the correlation-id, if specified) of the request message that this message contains the result of execution for.
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. See below for possible return values.

Depending on the status code the message body is either 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/${tenant_id}.
3. Client has established an AMQP link in role receiver with Hono using source address registration/${tenant_id}/${reply-id} (where reply-id can be any random id).

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
message-id	yes	properties	UTF-8 string	MUST contain the message ID used to match incoming message with the response message containing result of execution.
reply-to	yes	properties	UTF-8 string	MUST contain the address where replies are sent to.
correlation-id	no	properties	UTF-8 string	MAY contain an ID used to correlate the response to the original request. If the correlation-id is set it is used as the correlation-id property in the response otherwise the message-id is used.
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device to be queried.
action	yes	application-properties	UTF-8 string	MUST contain the action get.

The message body is empty.

The action property

Valid values for the action property and return values are:

Value	Description	Result status
get	Retrieves the device with the given device_id.	Device exists: 200, Device not found: 404
register	Registers a device with the given device_id.	Device registered: 201, Device already exists: 409
deregister	Deregisters a device with the given device_id.	Device deregistered. 204, Device not found: 404

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 200 (success) if the device with the given device_id is registered or 404 (not found) if the device_id is unknown to Hono.

Name	Mandatory	Location	Type	Description
correlation-id	yes	properties	UTF-8 string	MUST contain the message-id (or the correlation-id, if specified) of the request message that this message contains the result of execution for.
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. 200 for success i.e. the device is registered, 404 for failure i.e was not found or the user has no permission to see it.

The message body is empty.