Version 1.7.0.01 Changes

RestApi Device

Please note: This is very much a beta feature. Please report any problems using this feature so that we can address them as soon as possible.

This version adds a Rest API device that can be added into the system in order to send rest api commands to a rest api enabled device. In order to add a rest api device, click on the devices link and click the plus icon to add a new device. This will display the Address to Investigate dialog.

From the Investigation Type drop down, select Rest API. The dialog will change to show a name and a Url field.

Note: Name field only available as of 1.7.0.02. In 1.7.0.01 a name is derived from the url.

Enter a name for the device and the http address to send rest api commands to. Alternate ports may be used by using a colon and the port number:

After clicking Investigate, the device will be added to the system.

You will notice that for rest api devices, instead of a web page link you will see an edit link. The edit link will bring up a dialog for customizing the message header used by each rest api command:

The <UsernamePassword> chunk will be replaced by a basic authentication conversion of the user name and password. If no user name and password is defined, the Authorization may be removed. Currently this device only supports basic authentication. You can use this dialog to add custom header messages if they are needed by the rest api device.

The ChangeLogin link will allow you to assign a username and password to be used by rest api commands in the Authorization portion of the header.

Sending a command to the Rest API device

Once the device has been added to the system, it will be available in logic flows.

The SendToRestApi property needs to be structured in a specific way. The property value to send needs to have an operator (usually GET or PUT), a path, and optionally some data. Note that the path portion should be only the data after the device path. So for example:

PUT /my/path/url hello

When the device sends data it will prepend the device path when it sends to the device so that the http command becomes:

PUT http://172.16.1.97:4013/my/path/url hello

The data portion is optional and depends on the specification of the api you are trying to communicate with.

For example, a logic flow that sends to a rest api device when a button is pushed might look like:

Sap property memory slots and string builder memory slots can also be useful to build rest api commands according to the device’s specification and then pass the command through to the device whenever the memory slot changes.

Receiving data from the Rest API device

Please review the rest api technical details for more information on the pitfalls of using rest api to capture information from a device. In this case you would use the example above to send a request to the device probably using the GET operator. The information that is returned can be found in three read only properties (only seen if a start point is selected):

Response code returns the http response code that results from the last message sent. For example, it might return 200 if the request succeeded. Or it might return 404 if the path was not found. For more information on http response codes, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

The response data property will contain the actual data returned from the command. In many cases you may need a regex to filter the data for what you want to match in the logic flow.

The Response Success property will return true or false depending on whether the last rest api command was successful or not.

Rest API technical details

While rest APIs are currently very popular and therefore, we are adding them to PathfinderCore PRO out of necessity, we believe them to be generally ill suited for many broadcast applications. To provide an example we recently did some work with a product whose control protocol was exclusively Rest API. One of the first things our customer wanted to do was have PathfinderCore Pro do an action whenever a user pressed a button. The problem is that in order to detect that button push we would have needed to poll at 2.5 times the minimum amount of time the button might be held down. For computers this is not difficult until you start considering 25 buttons to a device and deployments of 600 to 700 devices. Now you have a situation where you are spending massive amounts of compute cycles on messages which basically say - nothing has changed. The point of that story is to say that applications that need low latency responses to state changes do not scale well with non-event driven protocols like Rest API. The consumer of such protocols needs to be cognizant of the cpu load ramifications for what they are doing. Currently if the user wants to poll, they would need to use an interval timer and a logic flow. We might add a way to pre program parameters that should be polled which would simplify that, but we opted not to do that in this incarnation because of the potential abuse possibilities described above. If all you care about is triggering a change and perhaps getting a response back that the change was made, then rest apis work well. But if real time state change information is required, then care needs to be taken and other options if available are advised. This article on Rest versus web sockets gives a great analogy using a general and his army of the difference between REST and a socket based architecture.

https://www.pubnub.com/blog/websockets-vs-rest-api-understanding-the-difference/

Which is to say use this feature with care.

TimeStamp Memory Slots

CalculateTime property

This version adds a calculate time write only property to time stamp memory slots. This property can be used to convert values from one time format to the pattern specified in the time stamp memory slot. For example, you could assign a number with either m, h, or s to the end and it would convert the value to the requested format in minutes hours or seconds. If the time stamp memory slot pattern was:

hh:mm:ss

and you passed in

100s

The value of the memory slot would become: 00:01:40.

Passing other time values than just numbers will try to interpret the value as time, convert it, and then express it in the correct pattern.