Difference between revisions of "IoT DAP Restful API"

Latest revision as of 10:10, 3 May 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>]

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

Clone

Endpoint for cloning resources :

/amtech/clone/resourceandlinks<resourceToCloneUri>?newname=<nameForClone> 

GET on this endpoint to clone the specified resource without persisting it, generating clones for all the links referenced in the resource. Ex. If called with a resource LLRPReader1, that has 2 anntenas, it will generate a clone for the each of the antennas and the LLRPReader.

/amtech/clone/resourceflat<resourceToCloneUri>?newname=<nameForClone>

GET on this endpoint to clone the specified resource without persisting it and without cloning the links referenced in the resource.

POST on both endpoint will clone the resource and persist it

The are entities' properties such as "proximity area" and "activity for observation production" whose values are always copied to the new resource as a reference, instead of cloning them.

Cloning is supported for:

• Thing types
• Observation types
• Supported properties
• Thing instances
• Observation instances

CRUD promises