Difference between revisions of "IoT DAP Restful API"

From AMTech WikiDocs
Jump to: navigation, search
(Example)
 
(10 intermediate revisions by 2 users not shown)
Line 20: Line 20:
 
===Observation instances (See [[Sensor's network#Observations and observation types|Observations and observation types]]) ===
 
===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
 
*Getting observation types with property _blankinstancepublished return a blank jsonld ready to be filled and send
**/amtech/linkeddata/types/composite/observation
+
: <code>/amtech/linkeddata/types/composite/observation</code>
 
*Sending observations  
 
*Sending observations  
**/amtech/things/events
+
: <code>/amtech/things/events</code>
  
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
Line 40: Line 40:
  
 
*Synchronous consumption of observation instances in topics
 
*Synchronous consumption of observation instances in topics
**/amtech/things/events?client=<client id>&topic=<topic uri>[&obstype=<obs type>]
+
: <code>/amtech/things/events?client=<client id>&topic=<topic uri>[&obstype=<obs type>]</code>
 
*topic (See [[Sensor's network#Topics|Topics]])  
 
*topic (See [[Sensor's network#Topics|Topics]])  
 
*targetthings (See [[Observers#Target things|Target things]])
 
*targetthings (See [[Observers#Target things|Target things]])
Line 49: Line 49:
 
===Thing instances (See [[Activities#Thing types|Thing types]])===
 
===Thing instances (See [[Activities#Thing types|Thing types]])===
 
*CRUD operations  
 
*CRUD operations  
**/amtech/things/entities
+
: <code>/amtech/things/entities</code>
 
*CRUD operation promises:
 
*CRUD operation promises:
**/promise/amtech/things/entities
+
: <code>/promise/amtech/things/entities</code>
  
 
===Commands (See [[Actions#Send command|Send command]])===
 
===Commands (See [[Actions#Send command|Send command]])===
Line 59: Line 59:
 
===Get observation production configuration (See [[Activities#Observation production configuration|Observation production configuration]])===  
 
===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]])
 
*Get observation configurations for a tenant/user tacking into account registered services and access control (See [[Access control#Actors|Actors]])
**'/amtech/system/queries/observationconfigfromactivities'
+
: <code>/amtech/system/queries/observationconfigfromactivities</code>
  
 
===Get instances by thing type===
 
===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]])  
 
*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>'
+
: <code>/amtech/things/entities/<thingType></code>
  
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
Line 82: Line 82:
 
==Asynchronous ([https://en.wikipedia.org/wiki/WebSocket web sockets])==  
 
==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:
 
*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...
+
: <code>wss://<user>:<pass>@<host>/amtech/push/things/events?client...</code>
  
 
===Observations (See [[Sensor's network#Crud observation|CRUD observations]])===
 
===Observations (See [[Sensor's network#Crud observation|CRUD observations]])===
 
*Asynchronous consumption of observation instances in topics using websocket’s pushing mechanisms (WIP)  
 
*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>]
+
: <code>wss://dap.amtech.mx/amtech/push/things/events?client=<client id>&topic=<topic uri>[&obstype=<obs type>]</code>
  
 
===Commands===
 
===Commands===
 
*Asynchronous consumption of commands using websocket’s pushing mechanisms (WIP)
 
*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>]
+
: <code>wss://dap.amtech.mx/amtech/push/things/commands?client=<client id>&thingtype=<thing type>&[&obstype=<obs type>]</code>
  
 
===Notifications (See [[Activities#Notification types|Notifications]])===
 
===Notifications (See [[Activities#Notification types|Notifications]])===
 
*Asynchronous consumption of notifications using websockets:
 
*Asynchronous consumption of notifications using websockets:
**wss://dap.amtech.mx/amtech/push/notifications[?clientid=<client id>]
+
: <code>wss://dap.amtech.mx/amtech/push/notifications[?clientid=<client id>]</code>
  
 
===Things===
 
===Things===
 
*Consumption through websocket of promise execution results:
 
*Consumption through websocket of promise execution results:
**/promise/amtech/results?client=<client_id>&thingtype=<thingtype>[&thinguri=<thinguri>]
+
: <code>/promise/amtech/results?client=<client_id>&thingtype=<thingtype>[&thinguri=<thinguri>]</code>
  
===Example===
+
<syntaxHighlight lang="javascript">
    "use strict";
+
"use strict";
    var websocket = require("websocket");
+
var websocket = require("websocket");
    var wsclient = new websocket.client();
+
var wsclient = new websocket.client();
    wsclient.on("connectFailed", function (error) {
+
wsclient.on("connectFailed", function (error) {
        console.log("Connect error: " + error.toString());
+
    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());
 
     });
 
     });
     wsclient.on("connect", function (connection) {
+
     connection.on("close", function () {
        console.log("WebSocket client connected");
+
         console.log("Connection closed");
        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");
+
     connection.on("message", function (message) {
    wsclient.connect("wss://dap.amtech.mx/amtech/push/notifications", null, null, {
+
        if (message.type === "utf8") {
         Authorization: "Basic " + token
+
            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
 +
});
 +
</syntaxHighlight>
 +
 
==Clone==
 
==Clone==
 
Endpoint for cloning resources :  
 
Endpoint for cloning resources :  
* /amtech/clone/resourceandlinks<resourceToCloneUri>?newname=<nameForClone>  
+
/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.
 
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>
+
/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.
 
GET on this endpoint to clone the specified resource without persisting it and without cloning the links referenced in the resource.
  
Line 141: Line 144:
 
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.
 
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 :
+
Cloning is supported for:
Entity type
+
* Thing types
Observation type
+
* Observation types
Supported properties
+
* Supported properties
Entity instances
+
* Thing instances
Observation instances
+
* Observation instances
 +
 
 +
==CRUD promises==

Latest revision as of 11: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>]

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