Difference between revisions of "IoT DAP Restful API"

Revision as of 10:50, 25 April 2016

Restful API

• Access control (See Access control and 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"

{   
    "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":""
}

• If the request is successful a jsonld representation of the resource will be return depending of the requested CRUD operation

Observation instances (See 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

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();
                    }
                });

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

Thing instances (See Thing types)

• CRUD operations
  • /amtech/things/entities
• CRUD operation promises:
  • /promise/amtech/things/entities

Commands (See 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 targetthings)

Get observation production configuration (See Observation production configuration)

• Get observation configurations for a tenant/user tacking into account registered services and access control (See 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 Actors)
  • '/amtech/things/entities/<thingType>'

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);
                    }
                });

Asynchronous (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 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 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
   });