Claiming
A claiming process may enable an end-user to claim Things and proof ownership thereof. Such a process is initially triggered via a claim message. This message can be sent to the Things service with the REST-like HTTP API or the things-client.
The following figure sketches such a workflow.
Claim a Thing at the REST API
An authenticated user [1] starts the claiming process by sending a (blocking) claim message [2a] to the Thing he wants to claim with the REST API. The message defines a timeout during which the request must be completed, and may carry additional custom payload.
The payload of the message is specified by the
solution to implement a custom process using the Integration Client
API.
The Bosch IoT Things service is only responsible for routing the message
to the client [2b] which operates the Thing to be claimed.
Find details regarding the claim
message at
Events
and Messages
resources.
The Solution interprets [3] and reacts respectively upon the received
claim message.
When the communication with the device terminates successfully, e.g. the
user pushes the correct button sequence on the device, the Solution
updates the permissions [4] of the Thing and replies to the message [5a].
The response may contain a custom payload and a HTTP status code. The
message is routed back to the REST API and completes the request [5b]
with the specified status code and payload.
If the request is not handled in time, the Things service completes the
request with a timeout.
Example
Our example provided on GitHub at RegisterForClaimMessages.java encapsulates within just one class the most simple way to simulate the device integration side for such a claiming process. The business implementation can be simulated by using the UI for trying out our REST-like API.
-
Run
RegisterForClaimMessages
.registerForClaimMessagesToSingleThing()
from within theExampleLauncher
class locally. This will create a Thing and log it’s ID. -
The example assumes that you have already a Solution registered with our service (for the API Token) and a User to authenticate [1] at the REST-like API.
-
Trigger a claim message [2a] (e.g. via HTTP API > Messages resource >
POST /things/{thingId}/inbox/claim
)- Copy the Thing ID logged in the previous step.
- The default timeout would be 60 seconds, however, you can set it up to 600 seconds.
- The payload field is not necessary, as the consumer (i.e.
RegisterForClaimMessages.java
) does not expect any payload. - Try it out.
-
The
RegisterForClaimMessages
handles the message (see code line 92) (In the figure above these would be [3], [4] and [5a].) -
Upon success the message “Thing ‘{}’ claimed from authorization subject ‘{}'" will be logged. From now on, the user should have permission to interact with “his” Thing.