Authentication

Once you have retrieved your keys, you can verify whether your keys and the REST server work E2E by issuing the following command:

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/ping"

Before you can start using the REST API, you must visit your profile page in the waylay application and fetch your API keys:

In waylay terminology, tasks are instantiated rules. There are two ways tasks can be instantiated:

one-off tasks, where sensors, actuators, logic and task settings are configured at the time the task is instantiated.
tasks instantiated from templates, where task creation is based on the template(which describes sensors, actuators and logic) and the task settings.

Create a task

There are mainly 2 ways to create a task, either by specifying the rule in the request, or by specifying the template with which the task needs to be instantiated.

Create a task with rule defined in the request

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "sensors": [
    {
      "label": "currentWeather_1",
      "name": "currentWeather",
      "version": "1.0.3",
      "sequence": 1,
      "properties": {
        "city": "Gent, Belgium"
      },
      "position": [173, 158]
    },
    {
      "label": "isWeekend_1",
      "name": "isWeekend",
      "version": "1.0.3",
      "sequence": 1,
      "position": [179, 369]
    }
  ],
  "actuators": [
    {
      "label": "TwitterDM_1",
      "name": "sendTwitterDM",
      "version": "1.0.1",
      "properties": {
        "screenName": "pizuricv",
        "message": "Great weekend!"
      },
      "position": [600, 199]
    }
  ],
  "relations": [
    {
      "label": "ANDGate_1",
      "type": "AND",
      "position": [353, 264],
      "parentLabels": ["currentWeather_1", "isWeekend_1"],
      "combinations": [["Clear", "TRUE"]]
    }
  ],
  "triggers": [
    {
      "destinationLabel": "TwitterDM_1",
      "sourceLabel": "ANDGate_1",
      "statesTrigger": ["TRUE"],
      "invocationPolicy": 1
    }
  ],
  "task": {
    "type": "periodic",
    "start": true,
    "name": "Rule created on 12/8/2015, 1:38:56 PM by veselin@waylay.io",
    "pollingInterval": 900
  }
}' "https://sandbox.waylay.io/api/tasks"

You can create a task without a need to create a template first. In order to create a task you will need to specify the following in the request:

sensors: list of sensors with required properties
actuators: list of actuators with required properties
relations: list of relations(gates) between sensors
triggers: list of conditions under which actuators/sensors get executed.
task: task related settings

Sensor settings are:

label: node label
name: sensor/actuator name
version
position: [X,Y] coordinates, e.g. [245, 205]
properties: key-value object of required properties
resource: resource
sequence: sequence number - applicable only for sensors, if omitted default is 1
dataTrigger: Boolean to indicate if sensor needs to be executed if data for resource is received
tickTrigger: Boolean to indicate if sensor needs to be executed on task tick
evictionTime: time (in milliseconds) after which sensor goes back to default state
pollingPeriod: time (in milliseconds) to give sensor it’s own tick

Actuator settings are:

label : node label
name : sensor/actuator name
version
position: [X,Y] coordinates, e.g. [245, 205]
properties: key-value object of required properties

Trigger settings are:

sourceLabel: label of the sensor / relation
destinationLabel: label of the actuator / sensor
invocationPolicy: integer number that defines how long to wait before firing the same actuator again, even if the condition is met.
statesTrigger: array of states under which to fire the actuator
stateChangeTrigger: object containing stateFrom and stateTo which can be a specific state or *

If neither statesTrigger nor stateChangeTrigger is specified when the destination is a sensor, this means that the destination sensor will be triggered after successful execution of the source sensor.

Relations express logical gates that can be defined between sensors. There are 3 types of relations: AND, OR and GENERAL.

Relations settings are:

label: gate label e.g. “ANDGate_1”
type: AND, OR or GENERAL
parentLabels: array of labels of sensors that are attached to this relation
combinations: array of arrays, such as [["Above", "Above"], ["Below", "Below"]]. Only GENERAL gate will have more than one array of combinations
position: [X,Y] coordinates, e.g. [245, 205]

Task settings are:

name
start flag to start a task, default yes
type: onetime, scheduled, reactive or periodic
other task type related settings, see further below

Create a task from a template

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test1",
  "template": "internet.json",
  "resource": "hello",
  "start": false,
  "type": "scheduled",
  "cron": "0/30 * * * * ?"
}' "https://sandbox.waylay.io/api/tasks"

In order to start a task from the template, you need to provide the following inputs:

name: task name
template: template name
resource: resource name
start: boolean to indicate whether task must be started after creation

Cron task

Cron specific input settings:

type : scheduled
cron: cron expression as defined in Cron format
timeZone: optional identifier of the time zone (e.g. “America/Los_Angeles” or “GMT-8:00”) in which the cron expression is to be interpreted

Periodic task

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test2",
  "template": "internet.json",
  "resource": "hello",
  "start": false,
  "type": "periodic",
  "frequency": 1000
}' "https://sandbox.waylay.io/api/tasks"

Periodic specific input settings:

type : periodic
frequency: polling frequency in milliseconds
pollingFixedRate : fixed rate or fixed delay (default: false - meaning fixed delay)
resetObservations: whether to clear observation before next invocation (default true)
parallel: whether to run sensors in parallel or sequentially (default true, meaning parallel)

Onetime task

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test3",
  "template": "internet.json",
  "resource": "hello",
  "type": "onetime"
}' "https://sandbox.waylay.io/api/tasks"

Onetime specific input settings:

type: onetime

Create a task with sensor properties in the request

In this example, we change addresses of the Ping sensors and the resource of node Ping_2:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
"name": "test4",
"template": "internet.json",
"resource": "hello",
"start": false,
"type": "scheduled",
"cron": "0/30 * * * * ?",
"nodes": [{
  "name": "Ping_1",
  "properties": {
    "sensor": {
      "name": "Ping",
      "version": "1.0.1",
      "label": "Ping_1",
      "requiredProperties": [
        {"address": "www.waylay.io"}
      ]
    }
  }
}, {
  "name": "Ping_2",
  "properties": {
    "resource": "newresource"
    "sensor": {
      "name": "Ping",
      "version": "1.0.1",
      "label": "Ping_2",
      "requiredProperties": [
        {"address": "sandbox.waylay.io"}
      ]
    }
  }
}]}' "https://sandbox.waylay.io/api/tasks"

You can also override node/sensor/actuator settings of the template before starting the task. These are the fields you can override:

nodes.[*].properties.cost (sequence number)
nodes.[*].properties.resource (string)
nodes.[*].properties.evictionTime (millis)
nodes.[*].properties.pollingPeriod (millis)
nodes.[*].properties.pollingFixedRate (boolean)
nodes.[*].properties.sensor.requiredProperties.*
nodes.[*].properties.actions.[*].requiredProperties.*

Update a task

This allows you update the task configuration. See also the documentation on getting a task’s configuration.

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X PUT -d '{
  "name": "test1",
  "template": "internet.json",
  "resource": "hello",
  "start": false,
  "type": "scheduled",
  "cron": "0/30 * * * * ?"
}' "https://sandbox.waylay.io/api/tasks/1"

Delete a task

Delete a task

curl --user apiKey:apiSecret -X DELETE "https://sandbox.waylay.io/api/tasks/1"

Start a task

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/tasks/1/command/start"

Stop a task

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/tasks/1/command/stop"

Getting a single task by id

Get information about a single task. Response will include template definition and task’s type and settings.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/{taskID}"

Getting an existing task’s configuration

Using this resource you can get the original task configuration that was posted to /api/tasks. Useful if you want to:

duplicate a task
update a task with a slightly modified configuration
run a batch injection on it’s template with the same configuration

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/{taskID}/conf"

Query multiple tasks

This call gives first 10 tasks (default behaviour), and if you need to filter your tasks, you can use a query language.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks"

Query task by name. For instance in this call you can retrieve all tasks that start with taskName.

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?name=taskName*"

Query to match tasks for resources with exactly the name

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?resource=resource1"

You can also query for tasks.

Task querying filtering

Query parameters are:

filter (fuzzy search on multiple properties)
name
resource
type (scheduled, periodic, …)
status (running, stopped, failed)
ids (comma separated string)
id (can be added multiple times)
tags (comma separated string)
tag (can be added multiple times)
plugin (mySensor or mySensor:1.0.3)
template (use 'null' for selecting tasks that don’t have a template)

All query parameters are combined with logical AND operator. That means that if you combine more than one parameter together you will only receive tasks that match all conditions.

You query task by a name using * characters to get a list of tasks that matches the input string.

If you query task by resource, input must match the resource name exactly. You can still receive more tasks in case they all have the same resource name.

Quering tasks and paging

curl --user apiKey:apiSecret \ 
  "https://sandbox.waylay.io/api/tasks?startIndex=1"

Default number of returned results is 10, and you can change this using hits parameter. For instance, this call will retrieve maximum 50 tasks, starting search from the task index 50. (second page of 50-per-page results)

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?startIndex=50&hits=50"

startIndex
hits (default 10, max. 100)

Paged result

If you want to retrieve the list as a paged list, add Accept header with value application/vnd.waylay.paged+json. The response will contain a JSON object with values, skip, limit and total fields.

To retrieve the next page, use skip+limit as startIndex and limit as hits

Get the total count of tasks

In order to retrieve the total task count, check the X-Count header of the response.

If you use the Accept: application/vnd.waylay.paged+json header, you will get the total count in the total field

In order to retrieve the total task count, check the header of the response (X-Count). In this example, we receive back 27 tasks:

curl --user apiKey:apiSecret -I "https://sandbox.waylay.io/api/tasks"

HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Wed, 07 Jan 2015 10:50:32 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Count: 27
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: X-Count
Strict-Transport-Security: max-age=31536000; includeSubdomains

Example: get the total count of running tasks

curl --user apiKey:apiSecret -I \
  "https://sandbox.waylay.io/api/tasks?status=running"

HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Wed, 07 Jan 2015 10:50:32 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Count: 5
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: X-Count
Strict-Transport-Security: max-age=31536000; includeSubdomains

Note on tasks and resources

Tasks and task nodes can be linked to a resource. There are some special node-related values you should know about:

$ - resource name will be inherited from the task resource name
$taskId - resource name will be inherited from the task ID

As an example if you have 3 nodes with resource $ and the task has resource foo, all three node-sensors will be triggered when data is injected for resource foo.

Batch tasks operations

There are 2 ways to perform batch operations on tasks.

asynchronously by queueing the operation on /batch
synchronously by applying the operation /tasks (deprecated, might time out with 50x errors)

Batch operation queue

list the queue

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/batch"

You get back an array with all queued and a history of max 20 batch operations ordered descending by time submitted.

[
  {
    "id":"f7fa8b2a-f7be-403c-9af7-e95c654b399f",
    "time":"2017-10-05T13:21:10.389Z",
    "operation":"Modify tasks by query: REMOVE"
  },
  {
    "id":"310282dd-377a-4a32-b1ed-599d0a1e9011",
    "time":"2017-10-05T13:21:10.388Z",
    "operation":"Modify tasks by query: REMOVE",
    "result":{"successful":[1,2],"failed":[]}
  }
]

post a batch operation

This api is the same as the direct batch operations api but:

instead of a PATCH /tasks you do a POST /batch (including query string params for filtering)
You get back an ID instead of the results
The results can then asynchronously be fetched using GET /batch/:id

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/batch?resource=testResource"
-H "Content-Type:application/json" -d '{ "operation": "command", "command": "remove" }'

{
  "id":"f7fa8b2a-f7be-403c-9af7-e95c654b399f",
  "time":"2017-10-05T13:21:10.389Z",
  "operation":"Modify tasks by query: REMOVE"
}

Direct operations (deprecated)

All the batch operations work with the same filters as querying for tasks, except the filter parameter which is not allowed because it’s not exact.

Delete multiple tasks

curl --user apiKey:apiSecret
-X PATCH "https://sandbox.waylay.io/api/tasks?ids=1,3,9"
-H "Content-Type:application/json"
-d '{ "operation": "command", "command": "remove" }'

curl --user apiKey:apiSecret
-X DELETE "https://sandbox.waylay.io/api/tasks?ids=1,3,9"

Modify existing tasks

curl --user apiKey:apiSecret -X PATCH "https://sandbox.waylay.io/api/tasks?ids=1,3,9"
-H "Content-Type:application/json" -d '{"operation": "xxx", ...}'

These calls will modify existing tasks in-place. Below an example of what such a request looks like:

Commands

This allows to start or stop a bunch of tasks. Valid commands are [start, stop, remove, reload]

The body should look like this

{
  "operation": "command",
  "command": "stop"
}

Reload tasks

This is mainly for applying template updates to existing tasks

{
  "operation": "command",
  "command": "reload"
}

Plugin updates

This will apply plugin version updates and re-instantiate the tasks.

The body should look like this (fromVersion can be an exact version or any)

{
  "operation": "updatePlugins",
  "updates": [
    {
      "name": "myActuator",
      "fromVersion": "1.0.1",
      "toVersion": "1.0.3"
    },
    {
      "name": "mySensor",
      "fromVersion": "1.1.0",
      "toVersion": "1.3.2"
    },
    {
      "name": "mySensor",
      "fromVersion": "any",
      "toVersion": "2.0.0"
    }
  ]
}

Modify task properties

This allows you to modify sensor / actuator properties while keeping the task Id.

The format used to modify properties is the same as when you create a task from a template. Updates will be merged with any previously provided properties.

{
  "operation" : "updateProperties",
  "nodes" : [ {
    "name" : "node1",
    "properties" : {
      "sensor" : {
        "requiredProperties" : [ {
          "prop1" : "updatedValue"
        }, {
          "prop1" : "updatedValue"
        } ]
      }
    }
  }, {
    "name" : "node2",
    "properties" : {
      "actions" : [ {
        "label" : "actuator1",
        "requiredProperties" : [ {
          "prop1" : "updatedValue"
        } ]
      } ]
    }
  } ]
}

Templates

Templates are generic rules that have not yet been associated to a particular device or instance. The same template can be instantiated many times as tasks, by associating device specific parameters to a specific template. This mechanism is operationally very efficient in the sense that templates only need to be developed once, but can then be instantiated many times. As an example, assume you generate a template for an appliance and in the field, you have 100k appliances deployed: then you would have one template and 100k tasks running on the waylay platform.

Create a new template

You can create a template using “simplified” logic representation (without Bayesian Network):

Template with sensors, actuators and relations

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name" : "testSimpleJSON",
  "sensors": [
    {
      "label": "currentWeather_1",
      "name": "currentWeather",
      "version": "1.0.3",
      "sequence": 1,
      "properties": {
        "city": "Gent, Belgium"
      },
      "position": [173, 158]
    },
    {
      "label": "isWeekend_1",
      "name": "isWeekend",
      "version": "1.0.3",
      "sequence": 1,
      "position": [179, 369]
    }
  ],
  "actuators": [
    {
      "label": "TwitterDM_1",
      "name": "sendTwitterDM",
      "version": "1.0.1",
      "properties": {
        "screenName": "pizuricv",
        "message": "Great weekend!"
      },
      "position": [600, 199]
    }
  ],
  "relations": [
    {
      "label": "ANDGate_1",
      "type": "AND",
      "position": [353, 264],
      "parentLabels": ["currentWeather_1", "isWeekend_1"],
      "combinations": [["Clear", "TRUE"]]
    }
  ],
  "triggers": [
    {
      "destinationLabel": "TwitterDM_1",
      "sourceLabel": "ANDGate_1",
      "statesTrigger": ["TRUE"],
      "stateChangeTrigger": {
        "stateFrom": "*",
        "stateTo": "FALSE"
      },
      "invocationPolicy": 1
    }
  ]
}' "https://sandbox.waylay.io/api/templates"

sensors: list of sensors with required properties
actuators: list of actuators with required properties
relations: list of relations(gates) between sensors
triggers: list of conditions under which actuators get executed.
task: task related settings

Sensor settings are:

label: node label
name: sensor/actuator name
version
position: [X,Y] coordinates, e.g. [245, 205]
properties: key-value object of required properties
resource: resource
sequence: sequence number - applicable only for sensors, if omitted default is 1
dataTrigger: Boolean to indicate if sensor needs to be executed if data for resource is received
tickTrigger: Boolean to indicate if sensor needs to be executed on task tick
evictionTime: time (in milliseconds) after which sensor goes back to default state
pollingPeriod: time (in milliseconds) to give sensor it’s own tick

Actuator settings are:

label : node label
name : sensor/actuator name
version
position: [X,Y] coordinates, e.g. [245, 205]
properties: key-value object of required properties

Trigger settings are:

sourceLabel: label of the sensor / relation
destinationLabel: label of the actuator / sensor
invocationPolicy: integer number that defines how long to wait before firing the same actuator again, even if the condition is met.
statesTrigger: array of states under which to fire the actuator
stateChangeTrigger: object containing stateFrom and stateTo which can be a specific state or *

Relations express logical gates that can be defined between sensors. There are 3 types of relations: AND, OR and GENERAL.

Relations settings are:

label: gate label e.g. “ANDGate_1”
type: AND, OR or GENERAL
parentLabels: array of labels of sensors that are attached to this relation
combinations: array of arrays, such as [["Above", "Above"], ["Below", "Below"]]. Only GENERAL gate will have more than one array of combinations
position: [X,Y] coordinates, e.g. [245, 205]

Create a new template using BN

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST
-d '{
    posterior: [ {
                    nodes: [ "CONNECTION", "Ping_1", "Ping_2", "Ping_3" ],
                    function: [ 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0 ]
                  } ],
    nodes: [ {
                states: [ "OK", "NOK" ],
                name: "CONNECTION",
                properties: {
                    position: [ 497, 235 ],
                    comment: "created by waylay",
                    cost: 1
                },
                type: "discrete",
                mode: "nature"
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_1",
                properties: {
                  position: [ 214, 317 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_1",
                    requiredProperties: [ { address: "www.google.com" } ] }
                },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_2",
                properties: {
                  position: [ 144, 163 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_2",
                    requiredProperties: [ { address: "www.waylay.io" } ] }
                },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_3",
                properties: {
                  position: [ 359, 62 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_3",
                    requiredProperties: [ { address: "www.yahoo.com" } ] }
                  },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              } ],
            name: "internet2.json"
          }' "https://sandbox.waylay.io/api/templates"

You can also create a new template that is defined as a Bayesian Network. Compared to previous call, this call allows you to define gates as a Conditional Probability Table (CPT) and also allows you to attach actuators to the likehood of a node being in a given state:

List all templates

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates"

Template listing filtering

Query parameters are:

filter (fuzzy search on multiple properties)
name
ids (comma separated string)
id (can be added multiple times)
plugin (mySensor or mySensor:1.0.3)

All query parameters are combined with logical AND operator. That means that if you combine more than one parameter together you will only receive tasks that match all conditions.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates?plugin=mySensor"

Get a template

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates/internet.json"

Update a template

Templates can be updated using the http PUT method. This however will not update any tasks using the template. You will need to do a batch reload operation on the tasks to accomplish that.

curl --user apiKey:apiSecret -X PUT "https://sandbox.waylay.io/api/templates/mytemplate"
-H "Content-Type:application/json" -d '{"name": "mytemplate", ...}'

Delete template

curl --user apiKey:apiSecret -X DELETE "https://sandbox.waylay.io/api/templates/internet.json"

Modifying existing templates (batch)

curl --user apiKey:apiSecret -X PATCH "https://sandbox.waylay.io/api/templates?plugin=myActuator"
-H "Content-Type:application/json" -d '{"operation": "xxx", ...}'

All the batch operations work with the same filters as querying for templates, except the filter parameter which is not allowed because it’s not exact. Some examples:

/templates?ids=mytemplate,myothertemplate (specific templates)
/templates?plugin=mySensor (mySensor any version)
/templates?plugin=mySensor%3A1.0.1 (mySensor 1.0.1)

Plugin updates

This will apply plugin version updates to the templates. Optionally you combine this with a reload of all tasks instantiated from the updated templates. (reloadTasks optional boolean property that defaults to false)

The body should look like this (fromVersion can be an exact version or any)

{
  "operation": "updatePlugins",
  "updates": [
    {
      "name": "myActuator",
      "fromVersion": "1.0.1",
      "toVersion": "1.0.3"
    },
    {
      "name": "mySensor",
      "fromVersion": "1.1.0",
      "toVersion": "1.3.2"
    },
    {
      "name": "mySensor",
      "fromVersion": "any",
      "toVersion": "2.0.0"
    }
  ],
  "reloadTasks": true
}

Running a template over a batch dataset

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/templates/mytemplate/run" \
 -H "Content-Type:application/json" \
 -d '{
      "data": [
        [{
           "resource": "resource1",
           "temperature": 20
         },
         {
           "resource": "resource2",
           "co2": 100,
           "humidity": 0.4
         }],
        [{
           "resource": "resource1",
           "temperature": 21
         }
        ]
      ],
      "conf": {
        "resetObservations": false,
        "executeActuators": false,
        "resource": "resource1",
        "nodes":[
          {
            "name": "temp",
            "properties": {
              "resource":  "resource1"
            }
          }
        ]
      }
    }'

You can run a template without creating a task by providing it with groups of resource-based data to inject. This allows running a template on a backlog of data while getting the results back as a stream while they are being produced.

These are the options you can set:

resetObservations (default true) reset observations before injecting data
executeActuators (default false) by default we do not execute actuators, set this to true if you want actuation to happen.
resource (optional) sets the global resource for the running of the template. Relates to note on tasks and resources.

The request contains 2 parts, the data which is an array of arrays and conf for providing the template overrides like you do when instantiating a task from a template. Data is provided as an array of arrays where the outer array will control the number of invocations performed on the task. The resulting stream will have as many items as this array. The inner array constitutes of all messages that should arrive at the task during that invovation. They will be mapped to nodes using the resource property.

The results are returned as a application/x-ndjson stream. Whenever an invocation ends you will receive a new json concatenated with a newline. The request will end once all data has been worked through. In case of a single invocation this response can also be parsed as application/json

{
  "nodes": {
    "alarm": {
      "state": "OK",
      "probability": 1
    },
    ...
  },
  "sensors":{
    "alarm": {
      "executed": true,
      "result": true,
      "state": "OK",
      "rawData": {},
      "log": []
    },
    ...
  },
  "actuators": {
    "alarm": {
      "sms_send": {
          "executed": true,
          "result": true,
          "message": "SMS sent",
          "log": []
        }
      },
      ...
    },
    ...
  }
}
\n
{
... second result here ...
}
\n

Running a batch dataset through a graph/BN

curl --user apiKey:apiSecret -X POST \
  https://sandbox.waylay.io/api/templates/run \
  -H 'Content-Type: application/json' \
  -d '{
    "graph": {
       "sensors": [
          {
             "label": "streamingDataSensor_1",
             "name": "streamingDataSensor",
             "version": "1.1.3",
             "dataTrigger": true,
             "resource": "$",
             "properties": {
                "parameter": "temperature",
                "threshold": "22"
             }
          }
       ],
       "actuators": [
          {
             "label": "debugDialog_1",
             "name": "debugDialog",
             "version": "1.0.5",
             "properties": {
                "message": "Temperature above threshold {{streamingDataSensor_1.threshold}} : {{streamingDataSensor_1.data.temperature}}"
             }
          }
       ],
       "triggers": [
          {
             "destinationLabel": "debugDialog_1",
             "sourceLabel": "streamingDataSensor_1",
             "invocationPolicy": 0,
             "statesTrigger": [
                "Above"
             ]
          }
       ]
    },
    "data": [
        [
            {
                "resource": "inside",
                "temperature": 20
            }
        ],
        [
            {
                "resource": "inside",
                "temperature": 30
            }
        ]
    ],
    "conf": {
        "resetObservations": false,
        "executeActuators": false,
        "resource": "inside"
    }
}'

Similarly to Running a template over a batch dataset, you can also run a batch dataset through a graph or baysian network by POSTing a similar datastructure to /templates/run. Next to the data element and the optional conf element, the body should also contain a graph element which either contains a Simplified graph or a Bayesian network

The results are returned also as application/x-ndjson stream.

Discovery template

One (and only one) template can be marked as discovery template. This template will be run using the Running a template over a batch dataset on any new discovered resource, i.e. the first time data is injected in the engine for this resource. This can be used to associate metadata (e.g. a resource type) to the newly discovered resource. Any actuators that are triggered in the template will be executed.

Get the discovery template

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/discoveryTemplate"

This will return with status code 200 (OK) with the template in the body if there is a discovery template and with status code 204 (NoContent) if there is no discovery template

Set the discovery template

curl --user apiKey:apiSecret -X PUT \
   "https://sandbox.waylay.io/api/discoveryTemplate?name=<templateName>"

To mark a template as the discovery template, execute this PUT call with the template name as the name query parameter. If the call was successfull, the template templateName will be returned in the body of the response.

To unmark the discovery template (set no discovery template), execute this PUT call without specifying the name query parameter.

Plugs (Sensors, Actuators and Transformers)

Note: More about how to write plugs can be found here

Plug types

Sensors

Sensors can be considered a generalized form of input connector for the waylay platform. You can create sensors to acquire data from physical devices, databases, applications or online services. You do this by means of writing Javascript and defining metadata. Waylay provides many examples which you can use as a baseline to create your own sensors, specific to your application. On a technical level, a sensor can be considered as a function that, when called, returns the state it is in.

Actuators

Based on the outcome of the logic, you may want to take action, such as sending an alert, writing something in a database or acting on a physical system. You can take action based on any node being in a particular state, by attaching actuators to the particular node. As for the sensors, the waylay framework allows you to add your own definitions of actuators.

Transformers

Transformers can be used to transforming incoming messages, like decoding, transforming or validation.

Get list of all sensors

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/sensors"

Execute sensor

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "city": "Gent"
    }
  }' \
  "https://sandbox.waylay.io/api/sensors/weatherSensor/versions/1.0.1"

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "city": "Gent"
    }
  }' \
  "https://sandbox.waylay.io/api/sensors/weatherSensor"

You can sensor specific parameters in the call, like in this example where we provide city name to the weather sensor. If the version is omitted, the latest version of the sensor will be called.

Get list of all actuators

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/actions"

Execute actuator

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "address": "veselin@waylay.io",
      "subject": "test",
      "message": "hello world"
    }
  }' \
  "https://sandbox.waylay.io/api/actions/Mail/versions/1.0.1"

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "address": "veselin@waylay.io",
      "subject": "test",
      "message": "hello world"
    }
  }' \
  "https://sandbox.waylay.io/api/actions/Mail"

You can provide actuator specific parameters in the call, like in this example where we provide e-mail address and message to mail actuator. If the version is omitted, the latest version of the actuator will be called.

Get list of all transformers

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/transformers"

Execute a specific transformer version

The payload to transform should be provided as string in properties.data

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "data": "{\"temperature\": 123.4}",
      "resource": "resource1"
    }
  }' \
  "https://sandbox.waylay.io/api/transformers/transformTemperatureFloat/versions/1.2.1"

Execute the latest transformer version

The payload to transform should be provided as string in properties.data

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "data": "{\"temperature\": 123.4}",
      "resource": "resource1"
    }
  }' \
  "https://sandbox.waylay.io/api/transformers/transformTemperatureFloat"

In waylay terminology, sensor is it attached to the node. During the runtime of the tasks, you can either inspect the node, or set the state, or execute attached sensors.

Get current states

Get current states(posteriors) and raw data for the node

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

Get supported states

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1/states"

Set the state

curl --user apiKey:apiSecret -X POST  -d 'state=Alive' "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

Execute attached sensor

In this call below, we will execute Ping sensor on the task 759:

curl --user apiKey:apiSecret -X POST  -d 'operation=start' "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

At any time you can execute a sensor attached to the node. Please be aware that the state change will be inferred in that task right after the sensor execution.

Provisioning API

Resource type provides link to set of tasks that can run on the group of resources. It can also be used to define metrics interface (which is linked to the sensory information) and command interface which allows you to abstract actual actuators implementation (see later). With most of the IoT platforms, you would find a ResourceType called a “template”, since they refer to this sort of modeling as a way to model different device categories using the same JSON template. In our case, we use a template in the rules context. More importantly, our abstraction allows to model both “object templating” together with rules associations, as described further.

Provisioning API allows you to associate metadata with resource. Resources are either discovered by Waylay (as soon as data is pushed towards Waylay Broker) or you can as well create them using REST call.

Next to the resource CRUD related calls, Waylay allows you to create ResourceType entities, and let you link resource to a type using metadata (please see example below). As soon as a resource is linked to the resource type, all metadata values of that type are inherited for that resource. Resource can still overwrite any specific attribute in its metadata model.

Waylay also allows you to associate a resource to a parent resource (by setting the parentId). Using this feature, you can organise your resources in a hiërarchical structure. Currently waylay does NOT check for cyclic references. Also parentId can NOT be inherited from the linked resource type.

Let’s see how api works in practice:

Create resource

In this example, we create a resource mydevice_id and add two additional attributes: customer and label:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
    -d '{"id":"mydevice_id", "customer":"tenant1", "label": "helloWorld"}' \
    "https://sandbox.waylay.io/api/resources"

Example of creating a resource and immediately linking it to the resource type:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "id": "myDevice_id",
    "resourceTypeId": "resourceType_Id",
    "customer": "tenant1",
    "name": "helloWorld"
  }'
  "https://sandbox.waylay.io/api/resources"

Reserved keywords for metadata:

Symbol	Type	Meaning
`resourceTypeId`	optional[String]	id of the linked resource type
`parentId`	optional[String]	id of the parent resource
`name`	optional[String]	name of the resource, like testresource
`owner`	optional[String]	owner of the resource
`provider`	optional[String]	LoRA, Sigfox..
`providerId`	optional[String]	provder_123
`customer`	optional[String]	customer tenant name
`tags`	optional[List[String]]	(sequence of strings) // example [“Proximus”, “myTag”, “locationC”]
`location`	optional [Location type]	see below
`firmware`	optional[String]	1.2_1234
`lastMessageTimestamp`	optional[Integer]	(epoch time of the last contact)
`metrics`	optional[list[ResourceMetric]]	see below
`commands`	optional[Commands]	see Commands

Example of creating a resource with location:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
  -d '{
    "id": "mydevice_id4",
    "customer": "tenant1",
    "label": "helloWorld",
    "location" : {
      "lat" : 51,
      "lon": 3.71
    }
  }' \
  "https://sandbox.waylay.io/api/resources"

Reserved keywords for Location type:

Symbol	Type
`lat`	Double
`lon`	Double

Reserved keywords for ResourceMetric:

Symbol	Type	Example
`name`	String	Temperature
`valueType`	String	integer, double, boolean, string, enum
`valueChoices`	optional[list[String]]	[“OK”, “NOK”]
`metricType`	String	count / gauge / counter / timestamp (for events) default gauge
`unit`	optional[String]	SI units or non-SI units like Fahrenheit…
`maximum`	optional[Double]	0
`minimum`	optional[Double]	60

Example of creating a resource with a metric in the request:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
-d '
    {
      "id":"mydevice_id3",
      "customer":"tenant1",
      "label":"helloWorld",
      "metrics" : [
        {
          "name" : "Temperature",
          "unit":"C",
          "valueType": "double",
          "metricType": "counter" }]
      }' "https://sandbox.waylay.io/api/resources"

Reserved keywords for Metric type:

Symbol	Meaning
`rate`	a number per second (implies that unit ends on ‘/s’)
`count`	a number per a given interval (such as a statsd flushInterval)
`gauge`	values at each point in time
`counter`	keeps increasing over time (but might wrap/reset at some point) i.e. a gauge with the added notion of “i usually want to derive this to see the rate”
`timestamp`	value represents a unix timestamp. so `sically a gauge or counter but we know we can also render the “age” at each point.

More about metric types you can find here metric20org

Commands for resource

Commands feature allows you to specify generic set of actuators for a resource, which at runtime get resolved to a specific actuator.

‘Create a resource with a SayHi command’

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_friendly_device",
    "commands" : [{
       "SayHi" : {
         "actuator" : {
            "name": "debugDialog",
            "version": "latest",
            "properties" : {
              "message": "Hello !"
            }
         }
       }
    }]
  }' "https://sandbox.waylay.io/api/resources"

The commands property must be an array of objects. Each object must have one property which is the name of the command. The value must be an actuator definition with following properties:

Property	Value
`name`	Name of an actuator
`version`	Exact version of the actuator or `latest`
`properties`	Json object with default values for the properties of the actuator

When a command is sent to the broker for the resource and with name SayHi, the engine will check the commands property of the resource’s metadata and see if there is a command SayHi mapped to an actuator. If there is such a property and the mapped actuator could be found, the properties for the actuator are merged with the actual message sent to broker and the actuator is executed for the resource and the merged properties.

‘Send a SayHi command for resource testresource’

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "name": "SayHi",
    "message": "Hello from this friendly resource"
  }' "https://data.waylay.io/resources/testresource/commands"

An interesting thing to note is that commands are sent over the broker and they are queued by the broker. That means that you can easily fan out all actuations this way, in case you need to send a lot of actuations in short period of time, without a worry whether sandbox can follow that sudden high load. Broker will make sure that they are all delivered with fastest pace, while at the same time, making sure they all have a chance to get executed by the sandbox.

Update resource

In order to update a resource, you need to put your resource Id in the path

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PUT \
    -d '{"resourceTypeId":"resourceType_Id", "customer":"tenant1", "name": "helloWorld"}' \
    "https://sandbox.waylay.io/api/resources/myDevice_id"

Partial resource update

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PATCH \
    -d '{"resourceTypeId":"resourceType_Id"}' \
    "https://sandbox.waylay.io/api/resources/myDevice_id"

Partial updates allow you to add/modify individual fields on a resource.

Delete resource

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X DELETE \
    "https://sandbox.waylay.io/api/resources/mydevice_id"

In order to delete a resource, you need to put your resource Id in the path

Retrieve resource

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]"

This would return something like

{
  "id": "testresource",
  "resourceTypeId": "SampleResourceType",
  "metrics":[{
    "name": "Temperature",
    "valueType": "double",
    "metricType": "counter",
    "unit": "C"
  }],
  "customField": "value"
}

In order to get a resource, you need to put your resourceId in the path

This will give you a denormalized view of a resource where properties that are inherited from the resourceType are merged with the properties specified at resource level.

HAL representation

curl -i --user apiKey:apiSecret -H "Accept: application/hal+json" \
  "https://sandbox.waylay.io/api/resources/[resourceId]"

This would return something like

{
  "id": "Ground floor",
  "name": "Ground floor",
  "#desks": 0,
  "_links": {
    "self": {
      "href": "/api/resources/Ground%20floor"
    },
    "children": {
      "href": "/api/resources/Ground%20floor/children"
    },
    "parent": {
      "href": "/api/resources/Office",
      "id": "Office"
    },
    "resourceType": {
      "href": "/api/resourcetypes/4539e0c2-578e-4470-8f14-2ed81d576e3a",
      "id": "4539e0c2-578e-4470-8f14-2ed81d576e3a"
    }
  }
}

To retrieve a more “enriched” representation of the resource, specify the Accept header as application/hal+json

The _links property provides hyperlinks to api endpoints to retrieve more information about the resource. Following are provided:

self: main reference to the resource
children: if the resource has children, the URI to retrieve all children of the resource
parent: if the resource has a parent, the URI to retrieve the parent of the resource
resourceType: if the resource is link to a resource type, the reference to retrieve the resource type

Retrieve normalized resource

curl -i --user apiKey:apiSecret \ 
  "https://sandbox.waylay.io/api/resources/[resourceId]?denormalized=false"

This would return something like

{
  "id": "testresource",
  "resourceTypeId": "SampleResourceType"
}

In order to get the normalized view of a resource, i.e. get only the properties that are specified on the resource level and not the ones inherited from the resource type level, set the query parameter denormalized to false.

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header.

Query resources

Paging is handled by skip and limit parameters

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?filter=car"

Resources can be queried by doing a GET request, if needed you can filter on these fields using the query string:

filter (partial match on multiple fields)
tag (can be added multiple times)
id (can be added multiple times)
provider
customer
resourceTypeId
lat, lon and distance (like 200km, 100m, …)
q (elasticsearch query string)
toplevelOnly (=true to search for resources without a parent)

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header. Resources will be returned in HAL format in the _embedded.values member. The result will next to the paging information (count, total, limit and skip) and the _embedded member, also contain a _links member that contains the links to

self reference
next reference to the next batch of results if there are more available
prev reference to the previous batch of results if this was not the first batch

Geo distance query

Find all resources within 10km from point (51.05,3.73)

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?lat=51.05&lon=3.73&distance=10km"

If your resources have coordinates specified in the location property (see Create resource), you find all resources within a specified distance from a point (specified by a lat and lon). See Distance units for the specification of distance

Retrieve resource change log

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources"

This returns a history of all changes to a resource sorted by change time descending.

If you want to page the list, you can do so by setting the Accept header to application/vnd.waylay.paged+json and using the skip and limit query parameters

Retrieve resource’s children

curl -i --user apiKey:apiSecret \                                
  "https://sandbox.waylay.io/api/resources/[resourceId]/children"

Retrieves the child resources of the specified resource, i.e. all resources that have the specified resource as (direct) parent.

Page with skip and limit query parameters. Use ?denormalized=false to retrieve the normalized representation of the children.

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header.

Retrieve resource command log

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]/commands"

will return something like

{
  "values": [
    {
      "name": "Say hi",
      "executionTime": "2018-09-24T13:59:10.377Z",
      "actuator": "debugDialog:LATEST",
      "result": {
          "success": true,
          "message": "Hi from resourcetype",
          "rawData": {}
      }
    },
    {
      "name": "Say his",
      "executionTime": "2018-09-24T13:58:56.075Z",
      "errorMessage": "Command 'Say his' not found"
    },
    {
      "name": "Say hi",
      "executionTime": "2018-09-24T10:47:59.739Z",
      "actuator": "debugDialog:LATEST",
      "result": {
          "success": true,
          "message": "resource brunocommand says hi",
          "rawData": {}
      }
    },
    ...
  ],
  "skip": 0,
  "limit": 10,
  "total": 16
}

This returns a paged list with the command exectutions. Page with skip and limit query parameters

Create resource type

In this example, we create a resource type and at the same time, we define metric types:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
  -d '{"id":"resourceType_Id", "customField":"value", "metrics" : [{"name" :"Temperature", "unit":"C", "valueType": "double", "metricType": "counter" }]}' \
   "https://sandbox.waylay.io/api/resourcetypes"

Reserved keywords for resource type:

Symbol	Type	Example
`id`	String	D12345 or UUID
`name`	optional[String]	device_123
`provider`	optional[String]	Proximus
`providerId`	optional[String]	123
`customer`	optional[String]	customer1
`metrics`	optional[List[ResourceMetric]]	list of metrics
`commands`	optional[Command]	Definition of commands
`templates`	optional[List[templates]]	Automatically create tasks by associating a template with a resource type

Update resource type

In order to update a resource type, you need to put your resource type Id in the path

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PUT \
    -d '{"resourceTypeId":"resourceType_Id", "customer":"tenant1", "name": "myResourceType"}' \
    "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Partial resource type update

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PATCH \
    -d '{"customer":"tenant2", "customField":"value"}' \
    "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Partial updates allow you to add/modify individual fields on a resource type.

Delete resource type

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X DELETE \
   "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Retrieve resource type

curl -i --user apiKey:apiSecret \ 
  "https://sandbox.waylay.io/api/resourcestypes/[resourceType_Id]"

In order to get a resource type, you need to put your resource type Id in the path

Query resource types

Paging is handled by skip and limit parameters

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resourcetypes?filter=car"

Resources can be queried by doing a GET request, if needed you can filter on these fields using the query string:

filter (partial match on multiple fields)
id (can be added multiple times)
q (elasticsearch query string)

Retrieve resource type change log

curl -i --user apiKey:apiSecret \
 "https://sandbox.waylay.io/api/resourcetypes/[resourceType_Id]/changes"

This returns a history of all changes to a resource type sorted by change time descending.

If you want to page the list, you can do so by setting the Accept header to application/vnd.waylay.paged+json and using the skip and limit query parameters

Automatically create tasks by associating a template with a resource type

The waylay task engine can automatically provision tasks for each new resource. This is configured in the metadata of the resource type. All you need to add is a field templates that contains what templates should be used and what task configuration should be applied to these managed tasks.

Resource type definition:

{
    "id": "4b80d00a-89f0-41a0-b6e5-d4423caca844",
     ...
     "templates": [
        {
            "templateName": "templatex",
            "type": "periodic",
            "frequency": 60000
        },
        {
            "templateName": "templatey",
            "type": "scheduled",
            "cron": "0 0 12 * * ?"
        }
     ]
}

If for example an existing resource’s type is set to the above type type then 2 tasks will be created.

In general these managed tasks are created/removed for these actions:

Resource created
Resource removed
Resource’s resourceType field updated
ResourceType’s templates field is updated
ResourceType is removed

Real-time (STREAM) data

The waylay application allows you to push raw data and states to the running tasks. Normally this is done via WaylayBroker which allows you to terminate many different protocols (WebSockets and REST), but if you wish, you can as well do it directly, calling STREAM related API call on the engine itself.

Push real-time raw data

Here is a REST invocation call that pushes temperature:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
        "resource": "home_X_room1",
        "data":{
          "object": "home_X_room1",
          "type": {
            "unit": "C",
            "dataType": "double",
            "collectedType": "instant"
          },
          "parameterName": "temperature",
          "value": 23.0,
          "collectedTime": 1420629467,
          "validPeriodSecs": 600
        }
      }' "https://sandbox.waylay.io/api/data"

If you need to process real time data in your sensors (like location, temperature etc.), you have two options:

use configuration property (see the interface spec) and fetch the data at runtime in the execute call
ask the framework to provide you with real time data and fetch the data from the task context (during the execution call of the sensor).

In case that real time data is provided to the sensors via the context (option 2), the plugin developer has put the responsibility of providing the real time data to the person that implements the REST call or websockets. When making use of this REST call, you must use the resource parameter as the identifier of your device (or any other “thing”). This is the same resource identifier that is associated with the task when you create it. In this way, the waylay framework can link the pushed raw data and the tasks(and sensors) that require this data.

When tasks gets invoked, the framework will provide the pushed raw data to all tasks (and the sensors) that match the resource identifier. You can create as many tasks as you want using the same resource identifier.

Here is the app view where you can test this feature(designer in debug mode):

You can also push several parameters at once, and you can as well skip most of the parameter’s attributes. For instance, with this call, we are pushing geolocation to the waylay platform, by specifying only longitude and latitude values. By default, waylay puts the validPeriodSecs of the parameter to 60 seconds, and collectedTime to the time the data was received:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST
-d '{
  "resource": "datasource",
  "data": [ {
            "parameterName": "latitude",
            "value": 51
          },
          {
            "parameterName": "longitude",
            "value": 3.73
          }
        ]
  }' "https://sandbox.waylay.io/api/data"

For more information please check Plugin SDK document.

Pushing states to the task

You can inject the state directly to the particular node in the task (as described before in the node section).

curl --user apiKey:apiSecret  --data "state=OPEN" -X POST https://sandbox.waylay.io/api/tasks/4/nodes/Door

For example, if you have a door with two states OPEN/CLOSED, you can push a state change from an external system to the task.

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
        "resource": "room_1",
        "nodes": [ {"node":"Door", "state": "OPEN"}]
      }' https://sandbox.waylay.io/api/data

Alarms

Alarms on the Waylay platform are a way of tracking/following up on a condition/state of a resource.

Create an alarm

curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
  -X POST
  -d '{
          "type" : "io.waylay.alarm.test",
          "timestamp" : "2011-09-06T12:03:27.845Z",
          "text" : "Some alarm documentation",
          "status" : "ACTIVE",
          "severity" : "MAJOR",
          "source" : { "id" : "12345", "self" : "..." }
        }'
   "https://alarms.waylay.io/alarm/alarms"

To create an alarm, you need to provide the following inputs:

type: type of the alarm
text: description of the alarm
severity: any of CRITICAL, MAJOR, MINOR or WARNING
source: a JSON object with an id field indicating the resource

Optional parameter :

status: any of ACTIVE, ACKNOWLEDGED or CLEARED (if not specified, created alarm will have status ACTIVE)
timestamp : ISO date string or number (indicating milliseconds since epoch) (if not specified, timestamp will be set to the receive time)

If an ACTIVE or ACKNOWLEDGED alarm with the same source.id and type exists, no new alarm is created. Instead, the existing alarm is updated by incrementing the countproperty and a new audit record of type io.waylay.alarm.EventOccuredAgain is added to the history.

Update an alarm

curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
  -X PUT
  -d '{
        "severity" : "minor",
        "status" : "acknowledged"
      }'
  "https://alarms.waylay.io/alarm/alarms"

Only severity and status can be updated. Either one or both must be specified.

You can only update an ACTIVE or ACKNOWLEDGED alarm. Updating a CLEARED alarm will result in a response code 412 Precondition Failed

Please notice that if the update actually doesn’t change anything (i.e. request body contains data that is identical to already present data in the database), there will be no audit record added.

Deletion of a single alarm

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Deletion of alarms in bulk

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms?source=..."

You can delete multiple alarms by specifying at least one filter in the query string. The possible filters are the same as the filters for quering the alarms (see below): type, status, source, dateFrom, dateTo

Get an alarm

curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Will return something like

{
    "id": "02eee99c-cd32-4fd0-9a35-89fa15570ccc",
    "self": "/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc",
    "creationTime": "2017-09-12T15:23:33.075Z",
    "type": "io.waylay.alarm.test",
    "text": "Some alarm documentation",
    "timestamp": "2017-09-12T15:23:33.074Z",
    "source": {
        "id": "bruno"
    },
    "severity": "MAJOR",
    "status": "CLEARED",
    "count": 1,
    "history": [
        {
            "id": "02114638-5d25-4031-b22a-40c883eb4c79",
            "type": "io.waylay.alarm.AlarmRaised",
            "text": "Alarm raised",
            "timestamp": "2017-09-12T15:23:33.076Z"
        },
        {
            "id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
            "type": "io.waylay.alarm.AlarmUpdated",
            "text": "Alarm updated",
            "timestamp": "2017-09-23T11:18:56.358Z",
            "changes": [
                {
                    "attribute": "status",
                    "oldValue": "ACTIVE",
                    "newValue": "CLEARED",
                    "type": "io.waylay.alarm.change.status"
                }
            ]
         }
    ]
}

An alarm has following fields:

Name	Type	Description
`id`	UUID	Uniquely identifies an alarm.
`self`	URI	Link to this alarm.
`creationTime`	ISO date string	Time when alarm was created in the database.
`type`	String	Identifies the type of this alarm.
`timestamp`	ISO date string	Time of the alarm.
`text`	String	Text description of the alarm
`source`	JSON Object	The resource that the alarm originated from, as object containing the “id” property.
`status`	String	The status of the alarm: `ACTIVE`, `ACKNOWLEDGED` or `CLEARED`.
`severity`	String	The severity of the alarm: `CRITICAL`, `MAJOR`, `MINOR` or `WARNING`.
`count`	Long	The number of times this alarm has been sent.
`history`	List of AuditRecord	History of modifications tracing property changes.

The history keeps a record of changes that have happened to the alarm. There are 3 different types of changes:

io.waylay.alarm.AlarmRaised: creation of the alarm
io.waylay.alarm.EventOccuredAgain: a request to create an alarm happened, but an alarm of the same type in status ACTIVE or ACKNOWLEDGED existed on the same source object at that moment
io.waylay.alarm.AlarmUpdated: some attribute(s) of the alarm where updated. The audit record will contain a list of changes that happened.

Query multiple alarms

curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms"

This above call gives the first 50 alarms. If you need to filter the alarms, you can use a query language

curl --user apiKey:apiSecret
  "https://alarms.waylay.io/alarm/alarms?source=6&status=ACTIVE&status=CLEARED"

This would give you a result like

{
    "self": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6",
    "next": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6&page=2",
    "total": 361,
    "alarms": [
        {
            "id": "586ac2f2-fbec-426a-b696-d63d6cb153ac",
            "self": "/alarm/alarms/586ac2f2-fbec-426a-b696-d63d6cb153ac",
            "creationTime": "2017-08-23T11:16:37.856Z",
            "type": "alarmtest",
            "text": "Another test alarm",
            "timestamp": "2017-08-23T11:16:08Z",
            "source": {
                "stuff": "blabla",
                "id": "6"
            },
            "severity": "MINOR",
            "status": "CLEARED",
            "count": 1,
            "history": [
                {
                    "id": "54597bdb-7409-4c47-b7ba-f08922b67ca2",
                    "type": "io.waylay.alarm.AlarmRaised",
                    "text": "Alarm raised",
                    "timestamp": "2017-08-23T11:16:37.856Z"
                },
                {
                    "id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
                    "type": "io.waylay.alarm.AlarmUpdated",
                    "text": "Alarm updated",
                    "timestamp": "2017-08-23T11:18:56.358Z",
                    "changes": [
                        {
                            "attribute": "status",
                            "oldValue": "ACTIVE",
                            "newValue": "CLEARED",
                            "type": "io.waylay.alarm.change.status"
                        }
                    ]
                }
            ]
        },
        {
            "id": "df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
            "self": "/alarm/alarms/df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
            "creationTime": "2017-08-18T15:54:51.180Z",
            "type": "alarmType",
            "text": "Another test alarm",
            "timestamp": "2009-02-13T23:31:30.128Z",
            "source": {
                "id": "6"
            },
            "severity": "MAJOR",
            "status": "ACTIVE",
            "count": 2,
            "history": [
                {
                    "id": "e64de65c-e3ef-482d-9eb7-32ca17d1e147",
                    "type": "io.waylay.alarm.AlarmRaised",
                    "text": "Alarm raised",
                    "timestamp": "2017-08-18T15:54:51.183Z"
                },
                {
                    "id": "b708f1e2-9da4-442b-ac6c-0120b0b11c08",
                    "type": "io.waylay.alarm.EventOccuredAgain",
                    "text": "Alarm event occured again",
                    "timestamp": "2017-08-21T07:26:47.209Z"
                }
            ]
        },
        ...
}

You can also query for alarms

Query criteria can be specified in the query string. Available criteria:

type: filter on type
status: filter on status
source: filter on id of the source
dateFrom: long (milliseconds since epoch) to filter on timestamp ( >= dateFrom)
dateTo: long (milliseconds since epoch) to filter on timestamp ( <= dateTo)

Different query parameters are combined with logical AND operator. Specifing the same query parameter (only for type, status and source) more then once, will be handled with a logical OR operation.

That means that if you combine e.g. status and source parameter, you will get only alarms on the specified source with the given status, but if you specify e.g. status twice (like status=ACTIVE&status=ACKNOWLEDGED) you will get all ACTIVE and ACKNOWLEDGED alarms

Paging is also supported through the query string with following options (results are sorted by descending timestamp):

page: page number (default: 1)
size: size of a page (default: 50)

The response does contain total number of alarms that fullfill the criteria. Also the response contains links to the current page self, to the next page if there is a next page and the previous page if there is one.

Vault

The Vault allows a user to store secret values, encrypted at rest. Performing operations on the Vault require you to be authenticated.

Creating / updating a secret

Creating a secret requires the following:

A Content-Type header to indicate what type of data is being stored
A payload that is valid according to the MIME type
A key, identified in the URL https://vault.waylay.io/vault/<key>

Vault supports the following MIME types:

Text

text/*
*/*+text
*/*+xml

Structured

application/json
*/*+json

Binary

application/octet-stream

Any other unrecognized MIME type is stored as a binary buffer, and will be returned as such.

$ curl -X PUT "https://vault.waylay.io/vault/my-secret" \
  -H "Content-Type: text/plain" \
  -d "this is a test"

$ curl -X PUT "https://vault.waylay.io/vault/my-json-secret" \
  -H "Content-Type: application/json" \
  -d '{ "hello": "world" }'

Retrieving a secret

If you”ve used the correct Content-Type header, you will receive your content exactly how Vault received it.

$ curl "https://vault.waylay.io/vault/my-secret"

Removing a secret

Simply send a DELETE request to the key you want to remove.

$ curl -X DELETE "https://vault.waylay.io/vault/my-secret"

Listing all secrets

$ curl "https://vault.waylay.io/vault"
[
  { "key": "my-text-secret" },
  { "key": "my-secret" }
]

Authentication

Task related calls

Create a task

Create a task with rule defined in the request

Create a task from a template

Cron task

Periodic task

Onetime task

Create a task with sensor properties in the request

Update a task

Delete a task

Start a task

Stop a task

Getting a single task by id

Getting an existing task’s configuration

Query multiple tasks

Task querying filtering

Related parameters:

Paged result

Get the total count of tasks

Note on tasks and resources

Batch tasks operations

Batch operation queue

list the queue

post a batch operation

Direct operations (deprecated)

Delete multiple tasks

Modify existing tasks

Commands

Reload tasks

Plugin updates

Modify task properties

Templates

Create a new template

Create a new template using BN

List all templates

Template listing filtering

Get a template

Update a template

Delete template

Modifying existing templates (batch)

Plugin updates

Running a template over a batch dataset

Running a batch dataset through a graph/BN

Discovery template

Get the discovery template

Set the discovery template

Plugs (Sensors, Actuators and Transformers)

Plug types

Sensors

Actuators

Transformers

Get list of all sensors

Execute sensor

Get list of all actuators

Execute actuator

Get list of all transformers

Execute a specific transformer version

Execute the latest transformer version

Node related calls

Get current states

Get supported states

Set the state

Execute attached sensor

Provisioning API

Create resource

Commands for resource

Update resource

Partial resource update

Delete resource

Retrieve resource

HAL representation

Retrieve normalized resource

Query resources

Geo distance query

Retrieve resource change log

Retrieve resource’s children

Retrieve resource command log

Create resource type

Update resource type