View source for IoT DAP Restful API

== DAP Restful API ==
*Access control (See [[Access control|Access control]] and [[Access control#Actors|Actors]]) 
**Restful API requires a username and password to authenticate at client side.
*Result formats are json depending of the success of the request
*If an error occurred a jsonld "@type":"/amtech/linkeddata/types/composite/outputMsg"

<syntaxhighlight lang="jsonld">
{   
    "message":"Resource /amtech/things/entities/gpsDevice/gpsDeviceParkingDemo already exists",
    "targetResourceType":"/amtech/linkeddata/types/composite/entity/gpsDevice",
    "errorType":"amtech.utils.model.ResourceAlreadyExistException",
    "@type":"/amtech/linkeddata/types/composite/outputMsg",
    "resource":"/amtech/things/entities/gpsDevice/gpsDeviceParkingDemo",
    "success":false,
    "messagedetail":""
}
</syntaxhighlight>
*If the request is successful a jsonld representation of the resource will be return depending of the requested CRUD operation 

===Observation instances (See [[Sensor's network#Observations and observation types|Observations and observation types]]) ===
*Getting observation types with property _blankinstancepublished return a blank jsonld ready to be filled and send
**/amtech/linkeddata/types/composite/observation
*Sending observations 
**/amtech/things/events

<syntaxhighlight lang="javascript">
rest.postJson(self.dapUrl + '/amtech/things/events', observation, options).on(
    'complete', function(data, response) {
                    if (response && response.statusCode && response.statusCode !== 200) {
                        complete(self.buildError(response, "Sending observation"), data);
                    } else if (data instanceof Error) {
                        complete(data);
                    } else if (data['success'] === false) {
                        complete(self.buildDapError(data, 'At DapClient sendObservation'), data);
                    } else {
                        complete();
                    }
                });
</syntaxhighlight>

*Synchronous consumption of observation instances in topics
**/amtech/things/events?client=<client id>&topic=<topic uri>[&obstype=<obs type>]
*topic (See [[Sensor's network#Topics|Topics]]) 
*targetthings (See [[Observers#Target things|Target things]])
*proximityarea (See [[Location|Location]])
*location (See [[Location|Location]])
*producer (See [[Sensor's network#Observations)

===Thing instances (See [[Activities#Thing types|Thing types]])===
*CRUD operations 
**/amtech/things/entities
*CRUD operation promises:
**/promise/amtech/things/entities

===Commands (See [[Actions#Send command|Send command]])===
Asynchronous consumption of commands using websocket’s pushing mechanisms (WIP)
Same as asynchronous consumption of observations. The command received, which is also an observation instance, will have the target type and target uri into the targetthings property. (See [[Sensor's network|targetthings]])

===Get observation production configuration (See [[Activities#Observation production configuration|Observation production configuration]])=== 
*Get observation configurations for a tenant/user tacking into account registered services and access control (See [[Access control#Actors|Actors]])
**'/amtech/system/queries/observationconfigfromactivities'

===Get instances by thing type===
*Get things instances by type for a tenant/user tacking into account registered services and access control (See [[Access control#Actors|Actors]]) 
**'/amtech/things/entities/<thingType>'

<syntaxhighlight lang="javascript">
rest.get(self.dapUrl + '/amtech/things/entities/gpsDevice', options).on(
    'complete', function (data, response) {
                    if (response && response.statusCode && response.statusCode !== 200) {
                        complete(self.buildError(response, "Getting plugins instances"), data);
                    } else if (data instanceof Error) {
                        complete(data);
                    } else if ('success' in data && !data['success']) {
                        complete(self.buildDapError(data, 'At DapClient getPluginsInstances'), data);
                    } else {
                        complete(null, data.members);
                    }
                });
</syntaxhighlight>

==Asynchronous ([https://en.wikipedia.org/wiki/WebSocket web sockets])== 
*In order to authenticate the request from a web browser using window.WebSocket object you can put the authentication credentials in the URL as:
**wss://<user>:<pass>@<host>/amtech/push/things/events?client...

===Observations (See [[Sensor's network#Crud observation|CRUD observations]])===
*Asynchronous consumption of observation instances in topics using websocket’s pushing mechanisms (WIP) 
**wss://dap.amtech.mx/amtech/push/things/events?client=<client id>&topic=<topic uri>[&obstype=<obs type>]

===Commands===
*Asynchronous consumption of commands using websocket’s pushing mechanisms (WIP)
**wss://dap.amtech.mx/amtech/push/things/commands?client=<client id>&thingtype=<thing type>&[&obstype=<obs type>]

===Notifications (See [[Activities#Notification types|Notifications]])===
*Asynchronous consumption of notifications using websockets:
**wss://dap.amtech.mx/amtech/push/notifications[?clientid=<client id>]

===Things===
*Consumption through websocket of promise execution results:
**/promise/amtech/results?client=<client_id>&thingtype=<thingtype>[&thinguri=<thinguri>]

===Example===
    "use strict";
    var websocket = require("websocket");
    var wsclient = new websocket.client();
    wsclient.on("connectFailed", function (error) {
        console.log("Connect error: " + error.toString());
    });
    wsclient.on("connect", function (connection) {
        console.log("WebSocket client connected");
        connection.on("error", function (error) {
            console.log("Connection error: " + error.toString());
        });
        connection.on("close", function () {
            console.log("Connection closed");
        });
        connection.on("message", function (message) {
            if (message.type === "utf8") {
                console.log("Received: '" + message.utf8Data + "'");
            }
        });
        process.on('SIGINT', function () {
            console.log("Closing connection...");
            connection.close();
            setTimeout(function () { console.log("Closed"); }, 5000);
        });
    });
    var token = new Buffer("user/tenant:password").toString("Base64");
    wsclient.connect("wss://dap.amtech.mx/amtech/push/notifications", null, null, {
        Authorization: "Basic " + token
    });