Example

RestApiServer command examples

Tag read command:

Figure 9: Tags used for the following command

• Reading tag values:

http://{{IP_address}}:{{HTTP_port}}/tag?cmd=read&path=/SITE01/LINE01/MACHINE01/*

• Response (only initial elements shown):

{
"tags": {
"COS_1DAY_PLC": {
"status": {
"value": 1,
"ts": "2021-05-17T10:50:33.624Z"
},
"data": {
"value": 0.965923547744751,
"quality": 192,
"ts": "2021-06-07T12:03:10.981Z"
}
},
"COS_1HOUR_PLC": {
"status": {
"value": 1,
"ts": "2021-05-17T10:50:33.624Z"
},
"data": {
"value": -7.589671326968528e-7,
"quality": 192,
"ts": "2021-06-07T12:26:15.495Z"
}
}
…
}
}
}

Alarm get command:Figure 10: alarms used for the following command

• Retrieving a list of alarms:

http://{{IP_address}}:{{HTTP_port}}/alarm?cmd=get&path=/SITE01/LINE01/MACHINE01/

• Response:

[
{
"path": "/SITE01/LINE01/MACHINE01/MINUTE_PLC.high_warning",
"description": "High value warning",
"priority": 2,
"remote": null,
"online": 1,
"status": 1,
"ts": 1623159717203,
"value": 30,
"ackInfo": {
"msg": "",
"user": "company01",
"options": {},
"node": "restapiserver-01",
"module": "RestApiServer"
}
},
{
"path": "/SITE01/LINE01/MACHINE01/MINUTE_PLC.high_alarm",
"description": "High value warning",
"priority": 3,
"remote": null,
"online": 1,
"status": 3,
"ts": 1623160265000,
"value": 40,
"ackInfo": null
},
{
"path": "/SITE01/LINE01/MACHINE01/SP_CMD_ECO_PLC.highValue",
"description": "High value alarm",
"priority": 2,
"remote": null,
"online": 1,
"status": 0,
"ts": 1621248633627,
"value": null,
"ackInfo": null
}
]

Backup export command:

• Retrieving backup data:

http://{{IP_address}}:{{HTTP_port}}/backup?cmd=export&name=20210504_RestApiServer_01

• Response:

UEsDBAoAAAAAAJhipFIAAAAAAAAAAAAAAAAKAAAASGlzdG9yaWFuL1BLAwQKAAgACACYYqRSAAAAAAAAAAAAAAAAEQAAAEhpc3Rvcmlhbi9hcGkubjNjTU5LCsIwEL3LrLNIKsbSnRdQcStdtOYJo2kjaVKEkrs7KgVX83nfhWbEicNIzUJDxzKNIjhOIcpaFEVM2SdqLnTs77gmUgthxpjOXcLnfchDj0jKaK1bRYkHhPwVrMj2hzyA597zjBMiB/fPsMLQbRH5Gi0hr4TRTd9iwWUvYWP2XirJyTeGOBhbabPRVV3vrC3lDVBLBwjixFR2lAAAAM4AAABQSwMECgAIAAgAmGKkUgAAAAAAAAAAAAAAABQAAABIaXN0b3JpYW4vY29uZmlnLm4zY1VQy04DMQz8lzkHlGy1

Link certSet command:

• Trusting a link via a POST request:

http://{{IP_address}}:{{HTTP_port}}/link?cmd=certSet

• Body:

{
"mode": "outbound",
"id": "pending/Node001__N3uron__LinkManager[E37C03E76FF5B212509957C572D40621214F4EA4]",
"action": "trust"
}

Figure 11: Pending link before sending request

Figure 12: Trusted link after sending request

Alarm acknowledge command:

• Acknowledging an alarm via a POST request:

http://{{IP_address}}:{{HTTP_port}}/alarm?cmd=ack

• Body:

{
"paths":
"/SITE01/LINE01/MACHINE01/MINUTE_PLC.high_warning"
}

Figure 13: Un-acknowledged alarm before sending request

Figure 14: Acknowledged alarm after sending request

Tag write command:

• Writing a tag value via a POST request:

http://{{IP_address}}:{{HTTP_port}}/tag?cmd=write

• Body:

{
"path": "/TagPostTest",
"value": 555
}

Figure 15: Tag value before sending the request

 Figure 16: Tag value after sending the request

Alarm history command:

• Retrieving history alarm values:

https://{{IP_address}}:{{HTTPS_port}}/alarm?cmd=history&path=/SITE01/LINE01/MACHINE01&start=2020-12-07T00:00Z&end=2021-12-07T00:00

• Response:

{
"request": {
"path": "/SITE01/LINE01/MACHINE01",
"start": 1607299200000,
"end": 1638835200000,
"options": {
"recurrent": false,
"filter": {
"path": null,
"status": null,
"priority": null
}
}
},
"data": [
{
"path": "/SITE01/LINE01/MACHINE01/MINUTE_PLC.high_alarm", "description": "High value warning",
"priority": 3,
"status": 2,
"ts": 1621728683000,
"value": 0,
"ackInfo": null
...
]
}

Tag history command:

• Request to retrieve historical values:

https://{{IP_address}}:{{HTTPS_port}}/tag?cmd=history&path=/SITE01/LINE01/MACHINE01/SECONDS_PLC&start=1619707394591&end=2021-08-29T15:10:51.174Z&options.mode=filter&options.deadband=50

• Response:

{
"request": {
"tag": "/SITE01/LINE01/MACHINE01/SECONDS_PLC",
"start": 1619707394591,
"end": 1630249851174,
"options": {
"mode": "filter",
"method": null,
"interval": null,
"deadband": 50
}
},
"data": [
[
1619707394591,
59.792999267578125
],
[
1621728057726,
2.38700008392334
],
[
1621728589850,
54.492000579833984
],
… 
]
}

Tag configuration command:

A new tag configuration can be loaded using the setConfigDatacommand :

• In this example two tags are  added to an already existing configuraton with only one tag by loading a new tag configuration. The request is configured as follows:

https://{{IP_address}}:{{HTTPS_port}}/module?cmd=setConfigData

• Body (only initial elements of “data” are shown):

{
"moduleName": null,
"configName":"tags",
"data":"{\"version\":{\"main\":1,\"editor\":1},\"result\":[\"Object\",{\"/\":[\"Object\",{\"description\":[\"String\",\"Root folder\"],\"groups\":[\"Object\",{}],\"tags\":[\"Object\",{\"
…
:[\"String\",\"avg\"],\"rate\":[\"Array\",[[\"Number\",0],[\"Number\",0]]]}]}],\"ae\":[\"Object\",{\"alarms\":[\"Object\",{}]}]}]}]}]}]}],\"editor\":{\"extends\":{\"module\":\".\"},\"modified\":1632730258896}}"
}

Figure 17: Tags available before sending set ConfigData command

Figure 18: Tags added after sending setConfigData command

Use of Postman collection

Postman is a platform for API development that amongst many other things allows testing API requests. N3uron provides a Postman collection, the use of which is strongly recommended in order to test the requests to the RestApiServer before implementing them in a production environment. In this collection, all N3uron's RestApiServer module requests are available and ready to use, with minimal adjustments.

To use the collection proceed as follows:

• Step 1: Importing N3uron's collection. The collection can be imported by downloading this file.

• Step 2: Unzip the file and upload the file in the “import” section of Postman

Figure 19: Postman workspace

Figure 20: Importing the file in postman

• Step 3: Enter the IP address of the target node and the ports in the “variables” section of the imported collection. For this example: IP address of the target node is 10.101.3.65, HTTP port is 3003 and HTTPS port is 3443.

Figure 21:   Configuring RestAPIServer collection’s variables

• Step 4: Choose the type of authentication configured in the user section in N3uron, and enter the username and password or token. For this example, the authentication type used is basic.

Figure 22: Configuring RestApiServer collection’s authentication parameters

• Step 5: Send a request. The following screenshot is the result of a link call.

Figure 23: Response of the link “get” command