Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "SensiNact/Bridge REST"
Line 14: | Line 14: | ||
URL: http://localhost:8080/sensinact/providers/fan/services/switch/resources/turn_on/ACT | URL: http://localhost:8080/sensinact/providers/fan/services/switch/resources/turn_on/ACT | ||
+ | |||
Method: POST | Method: POST | ||
+ | |||
Headers: ["Content-Type:application/json"] | Headers: ["Content-Type:application/json"] | ||
+ | |||
Body: EMPTY | Body: EMPTY | ||
Revision as of 07:32, 24 January 2019
Contents
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.
ACT on a device
Assuming you have a provide names _fan_ with a service _switch_ and a resource _turn_on_ and turn_off, both resource are resource action that present the action of turnning on or off a fan.
You can use RESTful API to perform this call, example:
Request
URL: http://localhost:8080/sensinact/providers/fan/services/switch/resources/turn_on/ACT
Method: POST
Headers: ["Content-Type:application/json"]
Body: EMPTY
Response
{
"triggered": [ { "name": "status", "type": "string", "value": "ON", "timestamp": 1548329494996 } ], "response": { "task": "ACT", "start": 1548329494996, "end": 1548329494996, "uri": "/fan/switch/turn_on", "status": "EXECUTED" }, "type": "ACT_RESPONSE", "uri": "/fan/switch/turn_on", "statusCode": 200
}
You can perform the same action in order to turn off the fan.
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
bysubscriptionId
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.