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/tasks"

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

Task related calls

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
    }
  ],
  "notes": [
    {
      "position" : [10, 10],
      "text" : "This will send a tweet when the weather is great"
    }
  ],
  "task": {
    "type": "periodic",
    "start": true,
    "name": "Rule created on 12/8/2015, 1:38:56 PM by veselin@waylay.io",
    "pollingInterval": 900,
    "tags" : {
      "myRef" : "d8933cd4-7c70-11e9-8f9e-2a86e4085a59"
    }
  }
}' "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.
• notes: list of notes as explanation for users
• 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]

Note settings are:

• position: [X,Y] coordinates, e.g. [10, 10]
• text: the text of the info box

Task settings are:

• name
• start flag to start a task, default yes
• type: onetime, scheduled, reactive or periodic
• resetObservations: whether to clear observation before next invocation (default true)
• parallel: whether to run sensors in parallel or sequentially (default true)
• 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",
  "start": false,
  "type": "scheduled",
  "cron": "0/30 * * * * ?",
  "tags" : {
     "myRef" : "d8933cd4-7c70-11e9-8f9e-2a86e4085a59"
  },
  "variables" : {
    "a" : "resourceA",
    "b" : "resourceB"
  }
}' "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 or
• variables: associate multiple resources to the task (json object/hashmap where the key is the variablename that is referenced in the template with $<variablename>)
• start: boolean to indicate whether task must be started after creation
• resetObservations: whether to clear observation before next invocation (default true)
• parallel: whether to run sensors in parallel or sequentially (default true)

Cron task

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

Cron specific input settings:

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

The schedule is expressed by one of below keys:

• cron: cron expression as defined in Cron format
• rrule: rrule expression as defined in RFC5545 3.8.5.3

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

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

Task tags

When creating a task, it is possible to specify tags for the task by which you can, later on, find the task back. You can specify this data in the tags object of the task settings. Any valid json is accepted. However, you can only search for task based on the toplevel tag keys with string, number or boolean values.

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.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 the configuration of an existing task

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"

Query tasks which have tag myRef equal to d8933cd4-7c70-11e9-8f9e-2a86e4085a59

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef=d8933cd4-7c70-11e9-8f9e-2a86e4085a59"

Query tasks which have tag myRef equal to ‘building1’ or ‘building2`

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef=building1&tags.myRef=building2"

Query tasks which have tag myRef

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef"

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)
• plugin (mySensor or mySensor:1.0.3)
• template (use 'null' for selecting tasks that don’t have a template)
• tags.<x> (can be added multiple times)

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.

If you specify a tags key multiple times, logical OR is applied for that key. If you don’t specify a value for a tags.<x> query parameter, all tasks which have a value for x in their tags are returned.

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"

Related parameters:

• 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
• $<variablename> - node will be linked to the resource specified at task startup in the variable variablename
• $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

Posting an operation to delete task 1, 3 and 9 in batch

curl --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/batch" \
 -H "Content-Type:application/json" \
 -d '{ 
       "entity": "task",
       "action": "delete",
       "query" : {
         "ids" : [1, 3, 9]
       } 
     }'

Result of above call

{
    "statusCode": 202,
    "uri": "/api/batch/afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
    "entity": {
        "id": "afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
        "queueTime": "2020-04-27T09:54:44.051Z",
        "operation": {
            "entity": "task",
            "action": "delete"
        }
    }
}

Result of GET https://sandbox.waylay.io/api/batch/afcea5a1-81df-44f6-bd34-e0b602a2cf3d

{
    "id": "afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
    "user": "22f6dfdf-a50c-4eab-953e-8d2e56891dbe",
    "operation": {
        "entity": "task",
        "action": "remove",
        "description": "Modify tasks filtered by ids=1,3,9 REMOVE"
    },
    "queueTime": "2020-04-27T09:54:44.051Z",
    "finishedTime": "2020-04-27T09:54:44.129Z",
    "results": {
        "success": {},
        "failure": {
            "9": {
                "statusCode": 400,
                "error": "Task 9 can not be removed as it has not been stopped"
            },
            "3": {
                "statusCode": 400,
                "error": "Task 3 can not be removed as it has not been stopped"
            },
            "1": {
                "statusCode": 404,
                "error": "Task with id 1 can not found"
            }
        }
    }
}

The batch endpoint /api/batch allows you to post an operation to multiple tasks. This operation will be executed asynchronously. When posting an operation, the batch endpoint will return an url which you can use retrieve (GET) the status and results of the operation.

When posting an operation, you need to specify the action and the type of entities you want the operation to act on. You also specify a query that selects the entities and potentially (dependent on the action) also some parameters specific for the action.

When retrieving the status of the bulk operation (using the url from the response of the POST call), the response will contain the finishedTime when the operation has completely finished and a results object that has success and failure fields indicating (per queried entity if possible, else on a generic key) a statusCode and, for failure an error message

For tasks, the entity type is task.

All supported actions allow to select the tasks on which they will be performed using the same query filters as querying for tasks, except the filter parameter which is not allowed because it’s not exact.

Below you can find the supported actions on the tasks

Delete multiple tasks

curl --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/batch" \
 -H "Content-Type:application/json" \
 -d '{ 
       "entity": "task",
       "action": "delete",
       "query" : {
         "ids" : [1, 3, 9]
       } 
     }'

Start/stop/restart/reload existing tasks

curl --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/batch" \
 -H "Content-Type:application/json" \
 -d '{
       "entity" : "task",
       "action": "stop",
       "query": {
          "status": "running",
          "resource": "myResource"
       } 
     }'

This allows to start/stop/… a bunch of tasks. Valid commands are

• start
• stop
• restart
• reload (This is mainly for applying template updates to existing tasks)

Plugin updates

curl --user apiKey:apiSecret \
  -X POST "https://sandbox.waylay.io/api/batch" \
  -H "Content-Type:application/json" \
  -d '{
        "entity": "task",
        "action": "updatePlugins",
        "query" : {
          "ids" : [ 4, 7, 300 ]
        },
        "actionParameters" : {
          "updates": [
            {
              "name": "myActuator",
              "fromVersion": "1.0.1",
              "toVersion": "1.0.3"
            },
            {
              "name": "mySensor",
              "fromVersion": "any",
              "toVersion": "2.0.0"
            }
          ]
        }
      }'

This will apply plugin version updates to a bunch of tasks and re-instantiate the tasks.

The actionParameters key of the POST /api/batch body must be a json object with an updates array of objects with following keys:

• name: name of the plug
• fromVersion: the version of the plug (can be an exact version or any)
• toVersion: the (exact) version of the plug to upgrade to

Modify task properties

curl --user apiKey:apiSecret \
  -X POST "https://sandbox.waylay.io/api/batch" \
  -H "Content-Type:application/json" \
  -d '{
        "entity": "tasks"
        "action": "updateProperties",
        "query": {
            "ids": [1,3,9]
        },
        "actionParameters" : {
            "nodes": [
             {
               "name" : "node1", 
               "properties" : {
                 "sensor" : {
                   "requiredProperties" : [ { "prop1" : "updatedValue"} ]
                 }
               }
             }, 
             {
               "name" : "node2",
               "properties" : {
                 "actions" : [ 
                   {
                     "label" : "actuator1",
                     "requiredProperties" : [ { "prop1" : "updatedValue"} ]
                   } 
                 ]
               }
             }
           ]
        }
      }'

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

The actionParameters object of the POST /api/batch body must contain a nodes key which is an array of objects. The format of these object is the same as the nodes array when you create a task from a template with sensor properties in the request.

Updates will be merged with any previously provided properties.

Templates

Templates are generic rules that have not yet been associated to a particular device/devices 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
    }
  ],
  "notes": [
    {
      "position" : [10, 10],
      "text" : "This will send a tweet when the weather is great in Ghent"
    },
    {
      "position" : [10, 50],
      "text" : "Change the city property in the currentWeather sensor if you want the weather for another city"
    }
  ],
}' "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.
• notes: list of notes as explanation for users
• name: the name of the template

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 (can be specified using $ or $<variablename>)
• 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]

Note settings are:

• position: [X,Y] coordinates, e.g. [10, 10]
• text: the text of the info box

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"

Will return the template properties, including the name, user and the Bayesian Network (nodes and posterior). If the template was created using simplified format, the simplified graph will be return in the simplifiedGraph property.

If the template uses multiple templated resources (using the $<variablename> format), the variablenames are returned in the variables property.

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 or variables if the template has multiple templated resources. 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. A discovery template cannot have multiple templated resources.

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"

Node related calls

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 Type 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 --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/resources" \
 -H "Content-Type: application/json" \
 -d '{
       "id": "mydevice_id", 
       "customer": "tenant1", 
       "label": "helloWorld"
    }'

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

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

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
alias	optional[String]	alias for the name of the resource, like testresource-alias
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
sensors	optional[Sensors]	see Sensors

Example of creating a resource with location:

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

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

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 --user apiKey:apiSecret \       
 -X POST "https://sandbox.waylay.io/api/resources" \
 -H "Content-Type: application/json" \
 -d '{
       "id" : "my_friendly_device",
       "greeter" : "Friendly device",
       "commands" : [{
          "SayHi" : {
            "actuator" : {
               "name": "debugDialog",
               "version": "latest",
               "properties" : {
                 "message": "Hello, says the {{greeter}} !"
               }
            }
          }
       }]
  }' 

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.

It is possible, in the properties of the actuator, to reference the metadata properties of the resource. They will be resolved to the actual value of the property at the moment of command execution. You can reference a metadata property by enclosing it’s name with {{ and }}. This is especially useful if you define commands at the resource type level, but need resource specific values

‘Send a SayHi command for resource testresource’

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

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.

Sensors for resource

You can also specify set of sensors that are applicable for a given resource. Please note that there is no explicit action taken by waylay platform on this meta key, unlike for commands, where waylay platform resolves a particular actuator for a given command call. Idea behind this abstraction is to assist integrations where an architect of the digital twin can specify which sensors from waylay library are applicable for a given resource (or resource type). For instance, you may have one sensor per metric, or multiple sensors for a given metric, or one sensor that is using multiple metrics. When calling a REST interface for meta, UI can be dynamically built based on set of capabilities for a resource both for actuations (using commands) and also associate set of sensors, next to supported metrics.

Create a resource with events sensor (which represents GoogleCalendar sensor)

curl --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/resources" \ 
 -H "Content-Type: application/json" 
 -d '{
    "id" : "my_friendly_device",
    "sensors" : [
      {
        "name": "events",
        "sensor": {
          "name": "GoogleCalendarStreamSensor",
          "version": "0.1.5"
        }
      }
    ]
  }' 

The sensors property must be an array of objects. Each object must have a name property that describes the sensor along with a sensor property which is an object containing following properties:

Property	Value
name	Name of a sensor
version	Exact version of the sensor or latest
properties	Json object with default values for the properties of the sensor

Sensor properties in meta

[
  {
    "name": "<custom-name-for-sensor>",
    "sensor": {
      "name": "<sensor-name>",
      "version": "<sensor-version>",
      "properties": {
        "<some-sensor-property>": "<property-value>",
        "<another-sensor-property>": "<property-value>"
      }
    }
  }
]

Json-ref

Building resource referencing a Weather Station resource

{
  "id": "e0d7b1cd-5bb7-4dfd-aa63-5ab1a5d5e3fa",
  "name": "Waylay Offices",
  "address": "Blekersdijk 33a",
  "city": "Ghent",
  "weatherStation": {
    "$ref": "/resources/04592b9a-e0c2-4e64-8c9a-202e50cd9275",
    "name": "Gents weer" 
  }
}

The Waylay Engine will also recognise metadata keys which are json objects with a $ref keyword as references to other resource if the value for the $ref is an URI that starts with /resources/.

When you reference these keys, using the META.$.<key> syntax, in the resource field of sensor nodes in a task definition, the Waylay Engine will “resolve” these at the start of the task and include the referenced resource as one of the task resources.

Update resource

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

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

Partial resource update

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

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

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

If you want to remove a field on a resource, you can do so by setting the field to null in the payload of the PATCH call

Delete resource

curl --user apiKey:apiSecret \
 -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

Filtered resource list request

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

Paging is handled by skip and limit parameters. If you have a large volume of resources, you can iterate of them like this:

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=0"
curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=1"
curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=2
  etc

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/[resourceId]/changes"

This returns the history of changes to a resource sorted by change time descending. By default only the last 10 most recent changes are returned.

If you want more changes, specify using the limit query parameter. If you want to skip some changes, use the skip query parameter

If you want to history to be returned as a paged list (so with values, total, limit and skip), set the Accept header to application/vnd.waylay.paged+json.

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 \
 -X POST "https://sandbox.waylay.io/api/resourcetypes" \
 -H "Content-Type: application/json" \
 -d '{ 
        "id":"resourceType_Id", 
        "customField":"value", 
        "metrics" : [
          { 
            "name":"Temperature", 
            "unit": "C", 
            "valueType": "double", 
            "metricType": "counter" 
          }
        ]
    }'

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 \
 -X PUT "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id" \
 -H "Content-Type: application/json" \
 -d '{
        "resourceTypeId": "resourceType_Id", 
        "customer":"tenant1", 
        "name": "myResourceType"
    }'

Partial resource type update

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

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

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

If you want to remove a field from a resource type, you can do so by setting the field to null in the payload of the PATCH call

Delete resource type

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

Retrieve resource type

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resourcetypes/[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)
• template: returns all resourceTypes that are associated with the template
• 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 the history of changes to a resource type sorted by change time descending. By default only the last 10 most recent changes are returned.

If you want more changes, specify using the limit query parameter. If you want to skip some changes, use the skip query parameter

If you want to history to be returned as a paged list (so with values, total, limit and skip), set the Accept header to application/vnd.waylay.paged+json.

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

Bulk delete of resources/resource types

Delete resources myDevice_id, mydevice_id3 and myWrongDevice in bulk

curl --user apiKey:apiSecret \
 -X POST "https://sandbox.waylay.io/api/batch" \
 -H "Content-Type:application/json" \
 -d '{ 
       "entity": "resource",
       "action": "delete",
       "query" : {
         "ids" : ["myDevice_id", "mydevice_id3", "myWrongDevice"]
       } 
     }'

Using the batch endpoint it is also possible to delete multiple resources or resource types in one api call.

To do this, you can POST a batch operation with delete action and
resource or resourcetype as entity to the /api/batch/ endpoint.

You need to specify the ids of the resources or resource types in the query key of the bulk operation.

Streaming (Real-time) data

Streaming data is data that is periodically updated and injected into a task so it can update it’s state. Injection of streaming data can happen directly to the api as shown below or by sending a message to the WaylayBroker which will then automatically be forwarded to the engine nodes linked to the same resource.

Streaming data is linked to a resource, this is a unique identifier that for example could be linked to a device or sensor. You can create as many tasks as you want that listen to this resource identifier.

Push Streaming (real-time) data

Below a direct REST call that pushes temperature:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
        "resource": "home_X_room1",
        "data":{
          "parameterName": "temperature",
          "value": 23.0,
          "collectedTime": 1420629467,
        }
      }' "https://sandbox.waylay.io/api/data"

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

• let the framework provide the injected streaming data to the sensor by linking it to a resource (eg. streamingDataSensor sensor)
• use a configuration property and fetch the data at runtime from the cloud cache (eg. waylayGetLatestItem sensor)

In the case that streaming data is injected into the sensor that is linked to the same resource (option 1), the sensor will be executed. It can then access the injected data using waylayUtil.

When making use of this API 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/node 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.

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 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 related information also see the Plugin SDK documentation

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.

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" : "..." }
          "task" : 3425,
          "myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
        }'
   "https://alarms.waylay.io/alarm/alarms"

To create an alarm, you need to provide the following mandatory 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)
• assignee: string field to indicate an assignee for the alarm

Any property in the creation json payload, that is not in the above mandatory or optional parameters will be saved in the additionalProperties field of the created alarm

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. Only the latest 1000 io.waylay.alarm.EventOccuredAgain audit records are kept in the history.

Update an alarm

curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
  -X PUT
  -d '{
        "severity" : "minor",
        "status" : "acknowledged",
        "assignee" : "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150"
      }'
  "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Only severity, status and assignee can be updated. At least one field 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

Clearing the assignee can be done by either setting it to the empty string ("") or null

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, severity, source, dateFrom, dateTo, assignee

Automatic deletion of alarms

Alarms (even alarms in ACTIVE or ACKNOWLEDGED status) are only kept in the system for one year after creation. Any alarm older then 1 year is automatically deleted.

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,
    "assignee": "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150",
    "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"
                }
            ]
         }
    ],
    "additionalProperties": {
        "task" : 3425,
        "myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
    }
}

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.
assignee	String	The assignee of the alarm, will not be present if there is no assignee
history	List of AuditRecord	History of modifications tracing property changes.
additionalProperties	JSON object	Additional properties that were present in the alarm creation JSON payload

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 (Remark: only the latest 1000 audit records of this type are kept in the history)
• 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
• severity: filter on severity
• 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)
• assignee: filter on assignee

Different query parameters are combined with logical AND operator. Specifying the same query parameter (only for type, status, severity 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.

Query for ACTIVE alarms with additional property task=3425

curl --user apiKey:apiSecret
  "https://alarms.waylay.io/alarm/alarms?status=ACTIVE&task=3425"

To query the alarms based on the value of an additional property of the alarm, you can add the key of the additional property as query parameter with value the value you expect the alarm to have.

Alarm events

Get application/x-ndjson stream of alarm events

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

{
  "eventtype": "io.waylay.alarm.AlarmRaised",
  "eventtime": "2019-03-01T10:07:58.772962Z",
  "alarm": {
    "id": "f8c692cf-80f7-4ade-a0e2-3d3586b64ba0",
    "creationTime": "2019-03-01T10:07:58.772958Z",
    ...
  }
}
\n
{
  "eventtype": "io.waylay.alarm.EventOccuredAgain",
  "eventtime": "2019-03-01T10:07:55.960860Z",
  "alarm": {
    "id": "9f2b01b4-5932-4d43-b7fe-e18aae47a93d",
    "creationTime":
    ...
  }
}
\n
{
  "eventtype": "io.waylay.alarm.AlarmUpdated",
  "eventtime": "2019-03-01T10:07:55.963025Z",
  "alarm": {
    "id": "ab4d4695-82c6-4eb5-9615-80d9f7cdbd68",
    ...
  },
  "changes": [
    {
      "attribute": "status",
      "oldValue": "ACTIVE",
      "newValue": "CLEARED",
      "type": "io.waylay.alarm.change.status"
    }
  ]
}
\n
...

You can listen for events on alarm.

Each event contains the eventtype, an eventtime and the alarm (with reduced properties) on which the event happened.

Possible eventtypes:

• io.waylay.alarm.AlarmRaised: a new alarm was created
• io.waylay.alarm.EventOccuredAgain: an alarm happened again
• io.waylay.alarm.AlarmUpdated: an alarm was updated

In case the event is a io.waylay.alarm.AlarmUpdated event, the event will also contain a changes property that indicates what properties of the alarm changed.

Vault

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

Vault uses a 256-bit Advanced Encryption Standard (AES) cipher in the Galois Counter Mode (GCM) with 96-bit initialization vectors. The initialization vector is randomly generated for every encrypted object.

When data is read the GCM authentication tag is verified during the decryption process to detect any tampering.

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" }
]

Converter

Authentication for the converter api can be done using an apiKey and apiSecret pair or can be done using a JWT token. If a jwt token is used --user apiKey:apiSecret can be replaced with -header 'Authorization: Bearer <jwt-token>'.

Create/update a converter

curl --user apiKey:apiSecret --request PUT -H 'Content-Type: application/json' 'https://converter.waylay.io/converter/:converter' \
--data-raw '{
               "template": "<escaped velocity template as string>",
                "type": "velocity"
            }'

The velocity template needs to be escaped so it can be sent in the json object as a string. An escape tool like this can be used.

Remove a converter

curl --user apiKey:apiSecret --request DELETE 'https://converter.waylay.io/converter/:converter'

Show configuration for converter

curl --user apiKey:apiSecret --request GET 'https://converter.waylay.io/converter/:converter'

Show all configuration for tenant

curl --user apiKey:apiSecret --request GET 'https://converter.waylay.io/converter/'

Convert data

This endpoint will convert a payload using a converter that is stored.

curl --user apiKey:apiSecret -i -X POST -H "Content-Type: multipart/form-data" \
--form 'payload=@<path-to-folder>/payload.json;type=application/json' 'https://converter.waylay.io/converter/:converter/convert?forward=true'

Forward querysting parameter

Forward can be either true or false, when true the converted payload will also be forwarded to broker.

Test a converter

Before creating your converter and making it available to the connectors, it is possible to test it using the test endpoint.

curl --user apiKey:apiSecret -i -X POST -H "Content-Type: multipart/form-data" \
--form 'config=@<path-to-folder>/config.json;type=application/json' \
--form 'payload=@<path-to-folder>/payload.json;type=application/json' 'https://converter.waylay.io/converter/test'