N3uron REST API calls
  • 09 Jun 2023
  • 9 Minutes to read
  • PDF

N3uron REST API calls

  • PDF

Article Summary

Alarm calls

N3uron REST API alarm calls provide information about the status and monitoring of alarms, and provide operations that can be made on alarms. In order to execute the desired command, alarm calls should start with http://<IP_address>:<HTTP_port>/alarm or https://<IP_address>:<HTTPS_port>/alarm, followed by '?' and the parameters (key-values). The character '&' should be used to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

Alarm GET commands

Get

Retrieves a list of alarms in the target node.

  • template:

https://<IP_address>:<HTTPS_port>/alarm?cmd=get&path=<path>&options.filter.path=<path_filter>


  • example:

https://127.0.0.1:3443/alarm?cmd=get&path=/SITE01/LINE01/MACHINE01/ALARMS/&options.filter.path=TEMPERATURE


  • parameters:
    • path: Path to browse for alarms. (Optional parameter)
    • options:
      • recurrent: Include subgroups. (Optional parameter)
      • filter: Filter parameters include :
        • path: Full alarm path regex filter (Optional parameter)
        • status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked). (Optional parameter)
        • priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical). (Optional parameter)

A concrete example of this command can be found in the Examples section of the manual.

Count

Request the alarm count.

  • template:

https://<IP_address>:<HTTPS_port>/alarm?cmd=count


  • example:

https://127.0.0.1:3443/alarm?cmd=count&path=/SITE01/LINE01/MACHINE01/ALARMS/&options.recurrent=true


  • parameters:
    • path: Path to browse for alarms (optional parameter)
    • options:
      • recurrent: Include subgroups.
      • filter: Filter include parameters:
        • path: Full alarm path regex filter (optional parameter)
        • status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked) (optional parameter)
        • priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical) (optional parameter)

History

Retrieves historical data of a specific alarm.

  • template:

https://<IP_address>:<HTTPS_port>/alarm?cmd=history&path=<path>&start=<start_date>&end=<end_date>


  • example:

https://127.0.0.1:3443/alarm?cmd=history&path=SITE01/LINE04/MACHINE01/GEARING/COS021&start=2020-12-07T00:00Z&end=2021-07-07T00:00


  • parameters:
    • path: Alarm path (mandatory parameter)
    • start: Start date. Must be an ISO string or a Unix epoch timestamp (mandatory parameter)
    • end: End date. Must be an ISO string or a Unix epoch timestamp (mandatory parameter)
    • options:
      • recurrent: Include subgroups.
      • filter: Filter parameters include:
        • path: Full alarm path regex filter (Optional parameter)
        • status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked) (Optional parameter)
        • priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical). (Optional parameter)

 A concrete example of this command can be found in the Example section of the manual.

Alarm POST commands

Ack

Acknowledges alarms.

  • template:

https://<IP_address>:<HTTPS_port>/alarm?cmd=ack


  • body template:

{
"paths": "<path>"
}


  • parameters:
    • paths: Alarm paths. Can be a single alarm, a comma-separated list or a JSON array (Mandatory parameter)
    • msg: Message to append to this acknowledgement (Optional parameter)

A concrete example of this command can be found in the Examples section of the manual.

Backup calls

N3uron REST API Server backup calls provide information about the status of configuration backups, and provide operations that can be made on backups. In order to execute the desired command, backup calls should start with http://<IP_address>:<HTTP_port>/backup or https://<IP_address>:<HTTPS_port>backup, followed by '?' and the parameters (key-values). The character '&' should be used to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

Backup GET commands

Get command

Retrieves a list of current configuration backups.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=get


Export command

Retrieves configuration backup in zip format encoded in Base64.

  • template:
https://<IP_address>:<HTTPS_port>/backup?cmd=export&name=<backup_name>


  • example:

https://127.0.0.1:3443/backup?cmd=export&name=20210504_RestApiServer_01


  • parameter:
    • name: Name of the backup file (Mandatory parameter)

A concrete example of this command can be found in the Examples section of the manual.

Backup POST commands

Create command

Creates a configuration backup of the target node.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=create


  • body template:
{
"name": "<name>"
}


  • parameters:
    • path: Name of the backup file (Mandatory parameter)
    • metadata:
      • description: Description of the backup file (Optional parameter)

Rename command

Renames a configuration backup.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=rename


  • body template:

{ 
"name": "<name>",
"rename": "<new_name>"
}


  • parameters:
    • name: Name of the backup file (Mandatory parameter)
    • rename: New name of the backup file (Mandatory parameter)

Delete command

Deletes a configuration backup.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=delete


  • body template:

{
"name": "<name>"
}


  • parameters:
    • name: Name of the backup file (Mandatory parameter)

Import command

Imports a previously exported configuration backup encoded in Base64.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=import


  • body template (example):

{
"name": "<name>",
"data":
"UEsDBAoAAAAAAJhipFIAAAAAAAAAAAAAAAAKAAAASGlzdG9yaWFuL1BLAwQKAAgACACYYqRSAAAAAAAAAAAAAAAAEQAAAEhpc3Rvcmlhbi9hcGkubjNjTU5LCsIwEL3LrLNIKsbSnRdQcStdtOYJo2kjaVKEkrs7KgVX83nfhWbEicNIzUJDxzKNIjhOIcpaFEVM2SdqLnTbQc5L+yuQ1pM8vw3Xp3qOhlMz/X9CTqk1EXEhVxld3Yh6+g/I4juPwqlO493Ovvysx6+6Gsn9uiSKVu22pK0wexfJT3msR6MIck4L/uxwZe+OOSTWNtgqDyGufIxRdFkLN6T7ct4NNDAa+WPHcYJWr6NLuiNJ56QVzQZtPonqsZYADENaxyiqHDmyZsvjm+41eknLACxIUlCjkA4AuJtRlPsvBq2MI1zxPwYkTX6v8PhBX5uNcwmYRYqS9AlJw57b0L8Ikgo4FoQ7UdJSmd0lqZRxA/i7QWoB7Sbh05lXyydzIWbbJA0FaQW0n4BmP8/J2z2kOL6oSlQLwjrGKB6

…

ipFIAAAAAAAAAAAAAAAAUAAAAYm9vdHN0cmFwL2xvZ2dlci5uM2N1T8sKwjAQ/Jc5B6FqW9ujH6AHj6WHtNlKJE0gTYsS8u9uQBAPsod9zs5MxEZ+0c6ijZil5lwIkNLBeS6TgKdlNQFth+vwoDFARIzOLs7Q75CsHAwptMGvJGBoI4MWwcuRkHqBSf+FdDg7figtREbz8Qfe4Ra8tncIaDs58EbJ15KZL+s8kIeo+8TxFR1Bz0BW8RFbcmrNrNiBvXCnJ501FmVzaqqm3FfH+pDSG1BLBwgaUmq1rQAAAAcBAABQSwMECgAIAAgAmGKkUgAAAAAAAAAAAAAAABUAAABib290c3RyYXAvbW9kdWxlcy5uM2PVU8FKQzEQ/Jc9B8nTWqE39aKXCj7Eg/SQZ7aogIjEuMi4xLTIwMDQwMS4yMjA4IiwKICAgICJGbGVldE1hbmFnZXJDbGllbnQiOiAiMS4wLjAtMjEwNDE2LjExMDItYmV0YSIKICB9Cn0="
}
}


  • parameters:
    • name: Name of the backup file (Mandatory parameter)
    • data: Backup file data, encoded in Base64 (Mandatory parameter)

Load command

Applies a configuration backup to the current node.

  • template:

https://<IP_address>:<HTTPS_port>/backup?cmd=load


  • body template:

{
"name": "<name>"
}
  • parameters:
    • name: Name of the backup file (Mandatory parameter)

Module calls

N3uron REST API Server module calls provide information about the status and monitoring of each module and operations that can be made on modules. In order to execute the desired command, module calls should start with http://<IP_address>:<HTTP_port>/module or https://<IP_address>:<HTTPS_port>/module, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

Module GET commands

Details command

Retrieves full details of instanced modules.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=details


GetInstalled command

Retrieves the list of installed modules.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=getInstalled


  • parameters:
    • filter: Module names. Can be a single filter, a comma-separated list or a JSON array (Optional parameter)

GetInstances command

Retrieves a list of instanced modules in the target node.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=getInstances


  • parameters:
    • filter: Module names. Can be a single filter, a comma-separated list or a JSON array (Optional parameter)

GetConfigList command

Retrieves a list of configuration files for every type of module.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=getConfigList&moduleType=<module_type>


  • example:

https://127.0.0.1:3443/module?cmd=getConfigList&moduleType=SiemensClient


  • parameters:
    • moduleType: Module type (Optional parameter)

 GetConfigPresent command

Indicates whether or not the configuration files for a specific module instance exist.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=getConfigPresent&moduleName=<module_name>


  • example:

https://127.0.0.1:3443/module?cmd=getConfigPresent&moduleName=Siemens


  • parameters:
    • moduleName: Module instance name (Optional parameter)

GetConfigData command

Retrieves configuration file content for a specific module instance.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=getConfigData&moduleName=<module_name>&configName=<config_name>


  • example:

https://127.0.0.1:3443/module?cmd=getConfigData&moduleName=Siemens&configName=logger


  • parameters:
    • moduleName: Module instance name (Optional parameter)
    • configName: Configuration name (Mandatory parameter)

Module POST commands

Start command

Starts a specific module.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=start


  • body template:

{
"moduleName": "<module_name>"
}


  • parameters:
    • moduleName: Module instance name (Mandatory parameter)

Stop command

Stops a module.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=stop


  • body template:

{
"moduleName": "<module_name>"
}


  • parameters:
    • moduleName: Module instance name (Mandatory parameter)

Restart command

Restarts a module.

  • template:

https://<IP_address>:<HTTPS_port>/module?cmd=restart


  • body template:

{
"moduleName": "<module_name>"
}


  • parameters:
    • moduleName: Module instance name (Mandatory parameter)

SetConfigData command

Sets a configuration file for a specific module instance.

  • template:

http://<IP>:<port>/module?cmd=setConfigData


  • body template:

{
"moduleName": "<module_name>",
"configName":"<configuration_name>",
"data":"<data>"
}


  • example:

http://{{IP_address}}:{{HTTP_port}}/module?cmd=setConfigData
{
"moduleName": "ModuleTest",
"configName":"logger", 
"data":"{\"version\":{\"main\":1,\"editor\":1},\"result\":[\"Object\",{\"console\":[\"Object\",{\"enabled\":true,\"level\":\"trace\"}],\"file\":[\"Object\",{\"enabled\":[\"Boolean\",true],\"level\":[\"String\",\"info\"],\"days\":[\"Number\",7]}]}],\"editor\":{\"extends\":{\"module\":null},\"modified\":1582974868907}}"
}


  • parameters:
    • moduleName: Module instance name (Mandatory parameter)
    • configName: Configuration name (for example: logger, API, users, tags, views, links, etc.) (Mandatory parameter)
    • data: Configuration file in JSON format (Mandatory parameter)
    • options:
      • restart: Restart module after saving new configuration (Optional parameter)
      • deleteData: Only applicable to module configuration file. List of deleted module instances to clean their data. Can be a single instance, a comma-separated list or a JSON array (Optional parameter).

N3uron REST API Server link calls provide operations and information about the status of the links in the target node. In order to execute the desired command, link calls should start with http://<IP_address>:<HTTP_port>/link or https://<IP_address>:<HTTPS_port>/link, followed by '?' and the parameters (key values), using '&' to separate each parameter. 

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

Links GET commands

Get command

Retrieves current links.

  • template:

https://<IP_address>:<HTTPS_port>/link?cmd=get

License calls

N3uron REST API Server link calls provide operations and information about the status of licenses in the target node. In order to execute the desired command, license calls should start with http://<IP_address>:<HTTP_port>/license or https://<IP_address>:<HTTPS_port>/license, followed by '?' and the parameters (key values), using '&' to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

License GET commands

GetUid command

Retrieves current node UID.

  • template:

https://<IP_address>:<HTTPS_port>/license?cmd=getUid


Get command

Retrieves a list of licenses of this node.

  • template:

https://<IP_address>:<HTTPS_port>/license?cmd=get


Read command

Retrieves details of a specific license.

  • template:

https://<IP_address>:<HTTPS_port>/license?cmd=read&name=<license_name>


  • example:

https://127.0.0.1:3443/license?cmd=read&name=DataServer01-20210216.143244.n3l


  • parameters:
    • name: Name of the license file (Mandatory parameter)

License POST commands

Add command

Adds a license to the target node.

  • template:

https://<IP_address>:<HTTPS_port>/license?cmd=add


  • body template:

{
"data": "{\"version\":\"1\",\"created\":\"2021-01-05T14:43:16.652Z\",\"signature\":\"5ce1ff1b7a9f911b49f653aa291bd375d8b2c53a0d57b0958ffe5f2341d",\"count\":1},{\"type\":\"SiemensClient\",\"tagAccess\":\"local\",\"count\":1},{\"type\":\"SmaClient\",\"tagAccess\":\"local\",\"count\
...
 ":1},{\"type\":\"SqlClient\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"UflExporter\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"WebVision\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"XantrexClient\",\"tagAccess\":\"local\",\"count\":1}]}]}" }


  •  parameters:
    • data: Data of the license file in JSON format (Mandatory parameter)

Remove command

Deletes a license in the target node.


  • template:

https://<IP_address>:<HTTPS_port>/license?cmd=remove


  • body template:

{
"name": "<license_name>"
}


  • parameters:
    • name: Name of the license file (Mandatory parameter)

System calls

N3uron REST API Server system calls provide operations and information about the status and monitoring of the target node. In order to execute the desired command, system calls should start with http://<IP_address>:<HTTP_port>/system or https://<IP_address>:<HTTPS_port>/system, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

System GET commands

Status command

Retrieves information regarding the status of the host system, current hardware, hostname, uptime, etc.

  • template:

https://<IP_address>:<HTTPS_port>/system?cmd=status


Errorcount command

Retrieves the number of errors in the current node. If there are no errors, 0 is returned, otherwise, it returns the number of errors (these can be caused by invalid tag configuration, invalid link configuration, etc...). 

  • template:

https://<IP_address>:<HTTPS_port>/system?cmd=errorCount

System POST commands

RestartService command

Restarts service.

  • template:

https://<IP_address>:<HTTPS_port>/system?cmd=restartService

Tag calls

N3uron REST API Server tag calls provide write operations and information about the status and monitoring of tags in the target node. In order to execute the desired command, tag calls should start with http://<IP_address>:<HTTP_port>/tag or https://<IP_address>:<HTTP_port>/tag, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.

<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).

Tags GET commands

Browse command

Retrieves a list of tags present in the defined path.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=browse&path=<path>


  • example:

https://127.0.0.1:3443/tag?cmd=browse&path=/SITE01/LINE01/MACHINE01/


  • parameters:
    • path: Path to browse for tags (Optional parameter)
    • options:
      • filter: Full tag path regex (Optional parameter)
      • flat: Receive an array instead of an object (Optional parameter)
      • recurrent: Include subgroups (Optional parameter)
      • hideTags: Do not receive tags (Optional parameter)
      • hideGroupsDo not receive groups (Optional parameter)

Read command

Retrieves values of tags present in the defined path.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=read&path=<path>


  • example:

https://127.0.0.1:3443/tag?cmd=read&path=/SITE01/LINE01/MACHINE01/*


  • parameters:
    • path: Path to read tag (Optional parameter)
    • options:
      • filter: Path to read tags. Entire groups can read using a wildcard * (Optional parameter)
      • recurrent: Include subgroups (Optional parameter)

A concrete example of this command can be found in the Examples section of the manual.

Details command

Retrieves full details of tags present in the defined path.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=details&path=<path>


  • example:

https://127.0.0.1:3443/tag?cmd=details&path=/SITE01/LINE01/MACHINE01/*


  • parameters:
    • path: Path to read tag (Mandatory parameter)
    • options:
      • filter: Path to read tags. Entire groups can read using a wildcard * (Optional parameter)
      • recurrent: Include subgroups (Optional parameter)

History command

Retrieves historical data of a specific tag.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=history&path=<path>&start=<start_date>&end=<end_date>


  • example:

https://127.0.0.1:3443/tag?cmd=history&path=/SITE01/LINE01/MACHINE01/AMPLITUDE&start=1619707394591&end=2021-04-29T15:10:51.174Z


  • parameters:
    • path: Tag path. (Mandatory parameter)
    • start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • options:
      • mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
      • method: Aggregation method when using aggregated mode. Can be first, last, min, max. and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
      • interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
      • deadband: deadband when using filter or delta mode (Optional parameter)
      • invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
      • limit: Maximum number of samples to return when using raw mode. (Optional parameter).

A concrete example of this command can be found in the Example section of the manual.

HistoryMany command

Retrieves historical data of tags.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=historyMany&paths=<path>&start=<start_date>&end=<end_date>


  • example:
https://{{IP_address}}:{{HTTPS_port}}/tag?cmd=historyMany&paths=/SITE01/LINE01/MACHINE01/AMPLITUDE,/SITE01/LINE01/MACHINE01/COS_1DAY_PLC&start=1619707394591&end=2021-09-29T15:10:51.174Z


  • parameters:
    • paths: Tag path list. Can be a single tag, a comma-separated list or a JSON array (Mandatory parameter)
    • start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • options:
      • mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
      • method: Aggregation method when using aggregated mode. Can be first, last, min, max and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
      • interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
      • deadband: Deadband when using filter or delta mode (Optional parameter)
      • invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
      • limit: Maximum number of samples to return when using raw mode. (Optional parameter).

HistoryFilter command

Retrieves historical data of tags (with regex filter).

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=historyFilter&path=<path>&start=<start_date>&end=<end_date>&options.filter=<tag_path>


  • example:

https://127.0.0.1:3443/tag?cmd=historyFilter&path=/SITE01/LINE01/MACHINE01&start=1619707394591&end=2021-04-29T15:10:51.174Z&options.filter=AMPLITUDE


  • parameters:
    • paths: Tag path list. Can be a single tag, a comma-separated list or a JSON array (Mandatory parameter)
    • start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
    • options:
      • filter: Full tag path Regex filter (Optional parameter)
      • recurrent: Include subgroups (Optional parameter)
      • mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
      • method: Aggregation method when using aggregated mode. Can be first, last, min, max and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
      • interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
      • deadband: Deadband when using filter or delta mode (Optional parameter)
      • invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
      • limit: Maximum number of samples to return when using raw mode. (Optional parameter).

Views command

Retrieves tag views.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=getViews

Tags POST commands

Write command

Writes a specific tag value.

  • template:

https://<IP_address>:<HTTPS_port>/tag?cmd=write


  • body template:

{
"path": "<tag_path>",
"value": <value>
}


  • parameters
    • path: Tag path (Mandatory parameter)
    • value: Value to write. The type must be the same as the configuration (number, Boolean or string) (Mandatory parameter)

A concrete example of this command can be found in the Examples section of the manual.


Was this article helpful?

What's Next