SensiNact/Bridge REST

Description

Application that is wired to a sensor information have two ways of fetching the actual sensor information: actively or passevely. In the first case the application is responsable for fetching the information at its convenience. The second option is to subcribe to the sensor, and a third-part application will be responsable for notifying when a new data is available.

Even though those are different approaches, usually application are built by combining those two. The first for initialize the values and the latter to later modification on the first value received.

Subscription

Request

URL: http://localhost:8090/sensinact/providers/light/services/switch/resources/status/SUBSCRIBE

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"callback":"http://localhost:8099/festival/back/info"}

It is important that the `callback` URL value, do not finish by a slash `/`, otherwise the callback will be called with a double slash `//`. `http://localhost:8099/festival/back/info//status8249578811484645003210`, this is an example of the address that will be receive the POST http call in response to sensor value update (duo to the subscription).

Response

{
 "response": {
   "subscriptionId": "status8249578811484645003210"
 },
 "type": "SUBSCRIBE_RESPONSE",
 "uri": "/light/switch/status",
 "statusCode": 200
}

Callback notification

The callback notification is done by a POST HTTP call from the gateway to the callback. An example of callback fired would be:

URL: http://localhost:8099/festival/back/info/status8249578811484645003210

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"notification":{"name":"state","type":"boolean","value":false,"timestamp":1484670944989},"type":"ATTRIBUTE_VALUE_UPDATED","uri":"/button/switch/state/value"}

Unsubscription

Request

URL: http://localhost:8090/sensinact/providers/light/services/switch/resources/status/SUBSCRIBE

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"usid":"status8249578811484582198073"}

Response

{
 "response": {
   "message": "unsubscription done"
 },
 "type": "UNSUBSCRIBE_RESPONSE",
 "uri": "/light/switch/status",
 "statusCode": 200
}

Remarks or improvements

• Replace usid by subscriptionId key in Unsubscription call to keep it coherent, they refer to the same element the sensiNact's internal callback ID ;
• Allows the user to specify how he wants to receive the callback, the method type (GET/POST) ;
• Option to list all subscriptions ;
• Option to remove subscription ;
• Allow user to specify if he wants this callback to be called with a specific id that he can identity. Avoiding the callback receiver to keep a local list mapping its objects to the sensiNact id ;
• Allow user to specify other notification channels, e.g. Websocket ;
• Remove the callback in sensiNact gateway if the callback is not reachable, otherwise it can be considered as a memory leakage.